This chapter describes the procedures and cryptographic credentials involved in establishing trust between entities.
The Device Attestation section provides mechanisms for Commissioners and Administrators to determine whether a Node is a genuine certified product before sharing sensitive information such as keys and other credentials. The Device Attestation feature relies on a Device Attestation Certificate (DAC) chain and on a Certification Declaration (CD).
The Node Operational Credentials section describes the credentials used by all Nodes to mutually authenticate each other during Certificate-Authenticated Session Establishment, including the Node Operational Certificate (NOC) chain. These credentials form the basis of how Nodes are identified and take part in securing operational unicast communication.
This chapter makes use of digital certificates in several subsections. All certificates within this specification are based on X.509v3-compliant certificates as defined in RFC 5280. The storage format of the certificates depends on application (e.g., DAC or NOC chain), but all certificates are directly compatible with X.509v3 DER representation after suitable loading or decompression.
In order to simplify further exposition, this subsection contains some common normative conventions that SHALL apply to all digital certificates described in this specification.
The following certificate formats are defined within this specification:
Compressed Node Operational credentials certificate chain elements in Matter Operational Certificate Encoding or "Matter Certificate" format:
Node Operational Certificate (NOC)
Intermediate CA Certificate (ICAC)
Root CA Certificate (RCAC)
Device Attestation certificate chain elements in Standard X.509 DER format:
Device Attestation Certificate (DAC): see Section 6.2.2.3, “Device Attestation Certificate (DAC)”
Product Attestation Intermediate (PAI): see Section 6.2.2.4, “Product Attestation Intermediate (PAI) Certificate”
Product Attestation Authority (PAA): see Section 6.2.2.5, “Product Attestation Authority (PAA) Certificate”
In addition to the standard DN (Distinguished Names) attribute types that appear in certificate Subject and Issuer fields, there are Matter-specific DN attribute types under the 1.3.6.1.4.1.1.37244
private arc. These are listed in Table 54, “Matter-specific DN Object Identifiers”. These OID values are assigned by the Connectivity Standards Alliance for use with Matter. All of these Matter-specific RDNs encode values normatively defined as scalars.
When used in Matter Operational Certificate (TLV) format (see Section 6.5, “Operational Certificate Encoding”), Matter-specific DN attribute types SHALL be encoded in Matter TLV as unsigned integers with the specified length.
When used in X.509 ASN.1 DER format certificate encoding, Matter-specific DN attribute types SHALL have their value encoded as either a UTF8String or PrintableString according to the table below. The values SHALL be encoded in network byte order as exactly twice their specified maximum octet length, encoded as uppercase hexadecimal number format without any separators or prefix, and without omitting any leading zeroes.
For example:
A scalar value 0x0123_4567_89AB_CDEF for matter-node-id:
Scalar maximal length: 8 octets (64 bits)
Resulting string: "0123456789ABCDEF" (without quotes)
Resulting length: 16 characters
A scalar value 0xAA_33CC for matter-noc-cat:
Scalar maximal length: 4 octets (32 bits)
Resulting string: "00AA33CC" (without quotes)
Resulting length: 8 characters
Table 54. Matter-specific DN Object Identifiers
TLV Tag | Matter name | Length (octets) | String length | ASN.1 OID | Types Allowed in X.509 |
17 | matter-node-id | 8 | 16 | 1.3.6.1.4.1.3724 4.1.1 | UTF8String |
18 | matter- firmware- signing-id | 8 | 16 | 1.3.6.1.4.1.3724 4.1.2 | UTF8String |
19 | matter-icac-id | 8 | 16 | 1.3.6.1.4.1.3724 4.1.3 | UTF8String |
20 | matter-rcac-id | 8 | 16 | 1.3.6.1.4.1.3724 4.1.4 | UTF8String |
21 | matter-fabric- id | 8 | 16 | 1.3.6.1.4.1.3724 4.1.5 | UTF8String |
22 | matter-noc-cat | 4 | 8 | 1.3.6.1.4.1.3724 4.1.6 | UTF8String |
N/A | matter-oid-vid | 2 | 4 | 1.3.6.1.4.1.3724 4.2.1 | UTF8String, PrintableString |
TLV Tag | Matter name | Length (octets) | String length | ASN.1 OID | Types Allowed in X.509 |
N/A | matter-oid-pid | 2 | 4 | 1.3.6.1.4.1.3724 4.2.2 | UTF8String, PrintableString |
Whenever an X.509 certificate contains Authority Key Identifier or Subject Key Identifier extensions, the associated Key Identifier SHALL be of a length of 20 octets, consistent with the length of derivation method (1) described in section 4.2.1.2 of [RFC 5280].
Further constraints related to the exact derivation appear in the following subsections:
Matter Certificates (NOC, ICAC, RCAC) Subject Key Identifier extension: see Section 6.5.11.4, “Subject Key Identifier Extension”
Matter Certificates Authority Key Identifier extension: see Section 6.5.11.5, “Authority Key Identifier Extension”
Device Attestation Certificate (DAC) extensions: see Section 6.2.2.3, “Device Attestation Certificate (DAC)”
Product Attestation Intermediate (PAI) Certificate extensions: see Section 6.2.2.4, “Product Attestation Intermediate (PAI) Certificate”
Product Attestation Authority (PAA) Certificate extensions: see Section 6.2.2.5, “Product Attestation Authority (PAA) Certificate”
All certificates SHALL NOT be longer than 600 bytes in their uncompressed DER format. This constraints SHALL apply to the entire DAC chain (DAC, PAI, PAA) and NOC chain (NOC, ICAC, RCAC).
Wherever Matter Operational Certificate Encoding representation is used, all certificates SHALL NOT be longer than 400 bytes in their TLV form. This constraint only applies to the NOC chain (NOC, ICAC, RCAC) since the DAC chain (DAC, PAI, PAA) only appears in DER format.
All certificates used within Matter SHOULD be as short as possible.
Certificate bodies are presented for exemplary purposes in multiple formats within this chapter. Since the translation of an X.509 certificate from ASN.1 DER format to human-readable text format may lose fidelity, especially with regards to equivalent types (e.g., PrintableString versus IA5String versus UTF8String) or serialization when non-standard OIDs are seen, textual examples SHALL NOT be considered to be normative. Only direct encoding of DER encoding, such as PEM blocks, should be used to further study the examples. In case of unforeseen divergence between an example certificate illustration and the normative rules expressed in prose, the normative prose SHALL take precedence over an ambiguous interpretation of an example.
Certification of a Device includes configuring the Device with immutable credentials that can be cryptographically verified. Device Attestation is the step of the Commissioning process whereby a Commissioner cryptographically verifies a Commissionee is in fact a certified Device. This chapter describes the Device Attestation Certificate (DAC) and the systems involved in the verification of a DAC.
The processes used to convey the DAC from a Commissionee to a Commissioner, how to verify that a Commissionee holds the private key corresponding to its DAC, and specifically how the DAC is verified are described in Section 6.2.3, “Device Attestation Procedure”.
This chapter refers to the signature algorithm ECDSA with SHA256 and to the elliptic curve secp256r1 (aka prime256v1 and NIST P-256) in compliance with the mapping for version 1.0 of the Matter Message Format of the cryptographic primitives as specified in Chapter 3, Cryptographic Primitives. Future versions of this specification might adapt these references accordingly.
All commissionable Matter Nodes SHALL include a Device Attestation Certificate (DAC) and corresponding private key, unique to that Device. The DAC is used in the Device Attestation process, as part of Commissioning a Commissionee into a Fabric. The DAC SHALL be a DER-encoded X.509v3-compliant certificate as defined in RFC 5280 and SHALL be issued by a Product Attestation Intermediate (PAI) that chains directly to an approved Product Attestation Authority (PAA), and therefore SHALL have a certification path length of 2.
The DAC also SHALL contain specific values of Vendor ID and Product ID (see Section 6.2.2.2, “Encoding of Vendor ID and Product ID in subject and issuer fields”) in its subject field to indicate the Vendor ID and Product ID provenance of the attestation certificate. See Section 6.2.3.1, “Attestation Information Validation” for how these are used.
The validity period of a DAC is determined by the vendor and MAY be set to the maximum allowed value of 99991231235959Z GeneralizedTime to indicate that the DAC has no well-defined expiration date.
-- Matter signatures are ECDSA with SHA256
MatterSignatureIdentifier ::= SEQUENCE {
algorithm OBJECT IDENTIFIER(id-x962-ecdsa-with-sha256) }
-- Matter Names
The notation used in this section to describe the specifics of the DAC uses the ASN.1 basic notation as defined in X.680. The notation below also leverages types defined in RFC 5280 such as AlgorithmIdentifier, RelativeDistinguishedName, Validity, Time, UTCTime, GeneralizedTime, or permitted extension types. Additionally, the notation below uses the ASN.1 definitions captured in the figure below:
-- The second to last RelativeDistinguishedName object in MatterDACName SEQUENCE SHALL contain an
-- attribute with type equal to matter-oid-vid and the last RelativeDistinguishedName object in the
-- SEQUENCE SHALL contain an attribute with type field set to matter-oid-pid MatterDACName ::= SEQUENCE OF RelativeDistinguishedName
-- There are two acceptable formats for MatterPA name. The first is identical to MatterDACName,
-- i.e. the second to last RelativeDistinguishedName object in MatterPAName SEQUENCE SHALL contain an
-- attribute with type equal to matter-oid-vid and the last RelativeDistinguishedName object in the
-- SEQUENCE SHALL contain an attribute with type field set to matter-oid-pid. In the second acceptable
-- format, the last element of the MatterPAName SEQUENCE SHALL be an RelativeDistinguishedName with
-- an attribute with type field set to matter-oid-vid MatterPAName ::= SEQUENCE OF RelativeDistinguishedName
-- Object definitions and references
-- X962 OIDs
id-x962 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x962(10045) }
id-x962-ecdsa-with-sha256 OBJECT IDENTIFIER ::= { id-x962 signatures(4) ecdsa-with- SHA2(3) ecdsa-with-SHA256(2) }
id-x962-prime256v1 OBJECT IDENTIFIER ::= { id-x962 curves(3) prime(1) prime256v1(7) }
-- CSA and Matter specific OIDs
csa-root OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) zigbee(37244) }
-- root arc for attestation certificates
matter-att-root OBJECT IDENTIFIER ::= { csa-root 2 }
-- Matter Device Attestation Certificate DN attribute for the Vendor ID (VID) matter-oid-vid OBJECT IDENTIFIER ::= { matter-att-root 1 }
-- Matter Device Attestation Certificate DN attribute for the Product ID (PID) matter-oid-pid OBJECT IDENTIFIER ::= { matter-att-root 2 }
The Device Attestation PKI hierarchy consists of the PAA, PAI and individual DAC. The public key from the associated PAI certificate is used to cryptographically verify the DAC signature. The PAI certificate in turn is signed and attested to by the Product Attestation Authority (PAA) CA. The public key from the associated PAA certificate is used to cryptographically verify the PAI certificate signature. The PAA certificate is an implicitly trusted self-signed root certificate. In this way, the DAC chains up to the PAI certificate, which in turn chains up to the PAA root certificate. A PAI SHALL be assigned to a Vendor ID value. A PAI MAY further be scoped to a single ProductID value. If a PAI is used for multiple products, then it cannot be scoped to a ProductID value, otherwise the Device Attestation Procedure will fail policy validations.
Commissioners SHALL use PAA and PAI certificates to verify the authenticity of a Commissionee before proceeding with the rest of the Commissioning flow.
The subject of all DAC and PAI certificates SHALL be unique among all those issued by their issuer, as intended by RFC 5280 section 4.1.2.6, through the use of RelativeDistinguishedName s that ensure the uniqueness, such as for example a unique combination of commonName (OID 2.5.4.3), serialNumber (OID 2.5.4.5), organizationalUnitName (OID 2.5.4.11), etc. The exact additional constraints, including for the subject field, for PAA, PAI and DAC certificates, are presented in the following subsections.
The following figure shows the Device Attestation PKI hierarchy.
Figure 34. Device Attestation PKI hierarchy
The following subsections contain references to VendorID and ProductID:
Section 6.2.2.3, “Device Attestation Certificate (DAC)”
Section 6.2.2.4, “Product Attestation Intermediate (PAI) Certificate”
Section 6.2.2.5, “Product Attestation Authority (PAA) Certificate”
The values for VendorID and ProductID, where possible or required in issuer or subject fields SHALL be encoded by only one of two methods, without mixing the methods within a given field:
The "preferred method", using Matter-specific RelativeDistinguishedName attributes:
VendorID encoded as AttributeTypeAndValue entry with type equal to 1.3.6.1.4.1.37244.2.1, and value respecting encoding specified in Section 6.1.1, “Encoding of Matter-specific RDNs”.
ProductID encoded as AttributeTypeAndValue entry with type equal to 1.3.6.1.4.1.37244.2.2, and value respecting encoding specified in Section 6.1.1, “Encoding of Matter-specific RDNs”.
A "fallback method" to support certificate authorities that only allow customary RFC 5280 OIDs in the arc {joint-iso-itu-t(2) ds(5) attributeType(4)} for type values in AttributeTypeAndValue entries of RelativeDistinguishedName elements is to encode them as substrings within the commonName attribute type ({joint-iso-itu-t(2) ds(5) attributeType(4) commonName(3)}):
VendorID value encoded with substring Mvid: followed by exactly 4 uppercase hexadecimal characters without elision of leading zeroes, anywhere within the commonName, such as for example:
VendorID 0xFFF1 (65521 decimal): Mvid:FFF1
VendorID 0x2A (42 decimal): Mvid:002A
ProductID value encoded with substring Mpid: followed by exactly 4 uppercase hexadecimal characters without elision of leading zeroes, anywhere within the commonName, such as for example:
ProductID 0xC20A (49674 decimal): Mpid:C20A
ProductID 0x3A5 (933 decimal): Mpid:03A5
The "preferred method" leaves more space for content in the commonName attribute type if present. It is also less ambiguous which may allow simpler processing of certificate issuance policy validations in CAs that support the Matter-specific RelativeDistinguishedName attributes, and simplify the audit of certificates where Vendor ID and Product ID appear.
The "fallback method" is present to support less flexible CA infrastructure.
Fallback method to encode VendorID and ProductID
The "fallback method" requires exactly 9 characters that are safe to use in both PrintableString and UTF8String for either VendorID or ProductID encoding. Since these VendorID and ProductID substrings have unambiguous format, they MAY be provided anywhere within a commonName value, and therefore separator selection does not need to be considered. Note that the standard RFC 5280 length limitation for commonName attribute value is 64 characters in total (see ub-common-name in RFC 5280).
Using the "fallback method" for embedding of VendorID and ProductID in commonName in the subject field of a Device Attestation Certificate claiming VendorID 0xFFF1 and ProductID 0x00B1 can be illustrated with the following valid and invalid examples (without the double quotes):
"ACME Matter Devel DAC 5CDA9899 Mvid:FFF1 Mpid:00B1": valid and recommended since easily human-readable
"ACME Matter Devel DAC 5CDA9899 Mpid:00B1 Mvid:FFF1": valid and recommended since easily human-readable
"Mpid:00B1,ACME Matter Devel DAC 5CDA9899,Mvid:FFF1": valid example showing that order or separators are not considered at all for the overall validity of the embedded fields
"ACME Matter Devel DAC 5CDA9899 Mvid:FFF1Mpid:00B1": valid, but less readable
"Mvid:FFF1ACME Matter Devel DAC 5CDAMpid:00B19899": valid, but highly discouraged, since embedding of substrings within other substrings may be confusing to human readers.
"ACME Matter Devel DAC 5CDA9899 Mvid:FF1 Mpid:00B1": invalid, since substring following Mvid: is not exactly 4 uppercase hexadecimal digits
"ACME Matter Devel DAC 5CDA9899 Mvid:fff1 Mpid:00B1": invalid, since substring following Mvid:
is not exactly 4 uppercase hexadecimal digits
"ACME Matter Devel DAC 5CDA9899 Mvid:FFF1 Mpid:B1": invalid, since substring following Mpid: is not exactly 4 uppercase hexadecimal digits
"ACME Matter Devel DAC 5CDA9899 Mpid: Mvid:FFF1": invalid, since substring following Mpid: is not exactly 4 uppercase hexadecimal digits
If either the Vendor ID (1.3.6.1.4.1.37244.2.1) or Product ID (1.3.6.1.4.1.37244.2.2) Matter-specific OIDs appear in any RelativeDistinguishedName in the subject or issuer fields of a certificate which is part of the Device Attestation Certificate chain path, then that certificate within the chain SHALL NOT have its commonName, if present, parsed for the "fallback method", in the rest of the issuer or subject field where the Matter-specific OIDs appear. In other words, considering a field such as subject or issuer, the presence of either of these OIDs as the type for any AttributeTypeAndValue within any RelativeDistinguishedName of that field SHALL cause the "fallback method" to be skipped altogether for that field. Otherwise, when the "fallback method" can legally be used, it SHALL only be used against AttributeTypeAndValue sequences where the type field is commonName ({joint-iso-itu- t(2) ds(5) attributeType(4) commonName(3)}) in the issuer and subject fields, and any mention thereafter of using or matching a "Vendor ID" or "Product ID" with regards to a Device Attestation Procedure step SHALL rely on values obtained with that method.
For example, if a given Product Attestation Intermediate certificate has a subject field employing a particular method of encoding the VendorID and ProductID, either using only Matter-specific OIDs or only the fallback method, then it follows that a Device Attestation Certificates issued by the certificate authority of that Product Attestation Intermediate SHALL have the same DistinguishedName content in its issuer field, so that the basic path validation algorithm works. That Device Attestation Certificate MAY however have the "fallback method" used within its subject field, if the Product Attestation Intermediate certificate authority is unable to encode/reflect the Matter-specific OIDs in RelativeDistinguishedName attributes within the subject field. The rules for whether to consider the canonical or "fallback method" for VendorID and ProductID encoding applies field by field independently for each instance of subject or issuer field found in certificates within the DAC chain.
The attributes in a DAC include:
AlgorithmIdentifier, BIT STRING }
DACTBSCertificate,
Certificate ::= SEQUENCE { tbsCertificate signatureAlgorithm signatureValue
DACTBSCertificate ::= SEQUENCE {
version INTEGER ( v3(2) ),
serialNumber INTEGER,
signature MatterSignatureIdentifier,
issuer MatterPAName,
validity Validity,
subject MatterDACName, subjectPublicKeyInfo SEQUENCE {
algorithm OBJECT IDENTIFIER(id-x962-prime256v1), subjectPublicKey BIT STRING },
extensions DACExtensions }
DACExtensions ::= SEQUENCE {
basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue BasicConstraints {cA FALSE} }),
keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue KeyUsage({digitalSignature})}),
authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}), subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL, authorityInformationAccess Extension({extnID id-pe-authorityInfoAccess}) OPTIONAL, subjectAlternateName Extension({extnID id-ce-subjectAltName}) OPTIONAL,
}
The DAC certificate SHALL follow the following constraints layered on top of the encoding specified by RFC 5280 within the TBSCertificate structure:
The version field SHALL be set to 2 to indicate v3 certificate.
The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256.
The issuer field SHALL be a sequence of RelativeDistinguishedName s.
The issuer field SHALL have exactly one VendorID value present.
The issuer field SHALL have exactly zero or one ProductID value present.
The subject field SHALL be a sequence of RelativeDistinguishedName s.
The subject field SHALL have exactly one VendorID value present.
The VendorID value present in the issuer field SHALL match the VendorID value found in
subject field.
The subject field SHALL have exactly one ProductID value present.
If a ProductID value was present in the issuer field, the ProductID value found in subject
field SHALL match the value found in the issuer field.
The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1.
The certificate SHALL carry the following Extensions:
Basic Constraint extension SHALL be marked critical and have the cA field set to FALSE.
Key Usage extension SHALL be marked critical and have the KeyUsage bitstring set to
digitalSignature
Authority Key Identifier
Subject Key Identifier
The certificate MAY also carry the following additional Extensions:
Extended Key Usage
Authority Information Access
Subject Alternate Name
Valid example DAC with associated private key, in X.509 PEM format
-----BEGIN CERTIFICATE-----
MIIB6TCCAY+gAwIBAgIIDgY7dCvPvl0wCgYIKoZIzj0EAwIwRjEYMBYGA1UEAwwP TWF0dGVyIFRlc3QgUEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQB
gqJ8AgIMBDgwMDAwIBcNMjEwNjI4MTQyMzQzWhgPOTk5OTEyMzEyMzU5NTlaMEsx HTAbBgNVBAMMFE1hdHRlciBUZXN0IERBQyAwMDAxMRQwEgYKKwYBBAGConwCAQwE
RkZGMTEUMBIGCisGAQQBgqJ8AgIMBDgwMDAwWTATBgcqhkjOPQIBBggqhkjOPQMB BwNCAATCJYMix9xyc3wzvu1wczeqJIW8Rnk+TVrJp1rXQ1JmyQoCjuyvJlD+cAnv
/K7L6tHyw9EkNd7C6tPZkpW/ztbDo2AwXjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB
/wQEAwIHgDAdBgNVHQ4EFgQUlsLZJJTql4XA0WcI44jxwJHqD9UwHwYDVR0jBBgw FoAUr0K3CU3r1RXsbs8zuBEVIl8yUogwCgYIKoZIzj0EAwIDSAAwRQIgX8sppA08 NabozmBlxtCdphc9xbJF7DIEkePTSTK3PhcCIQC0VpkPUgUQBFo4j3VOdxVAoESX kjGWRV5EDWgl2WEDZA==
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIHtcWp+0aVVH+DAQ38iXpphqmT7LfMnMD4V/kIqszwfuoAoGCCqGSM49 AwEHoUQDQgAEwiWDIsfccnN8M77tcHM3qiSFvEZ5Pk1ayada10NSZskKAo7sryZQ
/nAJ7/yuy+rR8sPRJDXewurT2ZKVv87Www==
-----END EC PRIVATE KEY-----
Human-readable contents of example DAC X.509 certificate
Certificate: Data:
Version: 3 (0x2)
Serial Number: 1010560536528535133 (0xe063b742bcfbe5d) Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, 1.3.6.1.4.1.37244.2.2 = 8000
Validity
Not Before: Jun 28 14:23:43 2021 GMT
Not After : Dec 31 23:59:59 9999 GMT
Subject: CN = Matter Test DAC 0001, 1.3.6.1.4.1.37244.2.1 = FFF1, 1.3.6.1.4.1.37244.2.2 = 8000
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:c2:25:83:22:c7:dc:72:73:7c:33:be:ed:70:73:
37:aa:24:85:bc:46:79:3e:4d:5a:c9:a7:5a:d7:43:
52:66:c9:0a:02:8e:ec:af:26:50:fe:70:09:ef:fc:
ae:cb:ea:d1:f2:c3:d1:24:35:de:c2:ea:d3:d9:92: 95:bf:ce:d6:c3
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:FALSE
X509v3 Key Usage: critical Digital Signature
X509v3 Subject Key Identifier: 96:C2:D9:24:94:EA:97:85:C0:D1:67:08:E3:88:F1:C0:91:EA:0F:D5
X509v3 Authority Key Identifier: keyid:AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88
Signature Algorithm: ecdsa-with-SHA256 30:45:02:20:5f:cb:29:a4:0d:3c:35:a6:e8:ce:60:65:c6:d0:
9d:a6:17:3d:c5:b2:45:ec:32:04:91:e3:d3:49:32:b7:3e:17:
02:21:00:b4:56:99:0f:52:05:10:04:5a:38:8f:75:4e:77:15:
40:a0:44:97:92:31:96:45:5e:44:0d:68:25:d9:61:03:64
-----BEGIN CERTIFICATE-----
MIIB0DCCAXegAwIBAgIIbec9lw3wZpAwCgYIKoZIzj0EAwIwRjEYMBYGA1UEAwwP TWF0dGVyIFRlc3QgUEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQB
gqJ8AgIMBDgwMDAwIBcNMjEwNjI4MTQyMzQzWhgPOTk5OTEyMzEyMzU5NTlaMDMx MTAvBgNVBAMMKE1hdHRlciBUZXN0IERBQyAwMDAxIE12aWQ6RkZGMSBNcGlkOjgw
MDAwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATCJYMix9xyc3wzvu1wczeqJIW8 Rnk+TVrJp1rXQ1JmyQoCjuyvJlD+cAnv/K7L6tHyw9EkNd7C6tPZkpW/ztbDo2Aw XjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUlsLZJJTq
l4XA0WcI44jxwJHqD9UwHwYDVR0jBBgwFoAUr0K3CU3r1RXsbs8zuBEVIl8yUogw CgYIKoZIzj0EAwIDRwAwRAIgbvYsHaGRTg1JzPTB6TqfVFPABF8LCYkEP1AvV7Ah
yL4CIACKW3A6YixqtqKfkwuvw81mMVymqafU8kx5k1c0zqbe
-----END CERTIFICATE-----
Valid example DAC with associated private key, in X.509 PEM format, using "fallback method" for VendorID and ProductID in Subject
Human-readable contents of example DAC X.509 certificate, using "fallback method" for VendorID and ProductID in Subject
Certificate: Data:
Version: 3 (0x2)
Serial Number: 7919366188737521296 (0x6de73d970df06690) Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, 1.3.6.1.4.1.37244.2.2 = 8000
Validity
Not Before: Jun 28 14:23:43 2021 GMT
Not After : Dec 31 23:59:59 9999 GMT
Subject: CN = Matter Test DAC 0001 Mvid:FFF1 Mpid:8000 Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:c2:25:83:22:c7:dc:72:73:7c:33:be:ed:70:73:
37:aa:24:85:bc:46:79:3e:4d:5a:c9:a7:5a:d7:43:
52:66:c9:0a:02:8e:ec:af:26:50:fe:70:09:ef:fc:
ae:cb:ea:d1:f2:c3:d1:24:35:de:c2:ea:d3:d9:92: 95:bf:ce:d6:c3
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:FALSE
X509v3 Key Usage: critical Digital Signature
X509v3 Subject Key Identifier: 96:C2:D9:24:94:EA:97:85:C0:D1:67:08:E3:88:F1:C0:91:EA:0F:D5
X509v3 Authority Key Identifier: keyid:AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88
Signature Algorithm: ecdsa-with-SHA256 30:44:02:20:6e:f6:2c:1d:a1:91:4e:0d:49:cc:f4:c1:e9:3a:
9f:54:53:c0:04:5f:0b:09:89:04:3f:50:2f:57:b0:21:c8:be:
02:20:00:8a:5b:70:3a:62:2c:6a:b6:a2:9f:93:0b:af:c3:cd:
66:31:5c:a6:a9:a7:d4:f2:4c:79:93:57:34:ce:a6:de
AlgorithmIdentifier, BIT STRING }
PAITBSCertificate,
Certificate ::= SEQUENCE { tbsCertificate signatureAlgorithm signatureValue
The attributes in a PAI certificate include:
PAITBSCertificate ::= SEQUENCE {
version INTEGER ( v3(2) ),
serialNumber INTEGER,
signature MatterSignatureIdentifier,
issuer Name,
validity Validity,
subject MatterPAName, subjectPublicKeyInfo SEQUENCE {
algorithm OBJECT IDENTIFIER(id-x962-prime256v1), subjectPublicKey BIT STRING },
extensions PAIExtensions }
PAIExtensions ::= SEQUENCE {
basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue BasicConstraints {cA TRUE, pathLen 0} }),
keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue KeyUsage({keyCertSign}|{cRLSign})}),
authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}), subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL
}
The PAI certificate SHALL follow the following constraints layered on top of the encoding specified by RFC 5280 within the TBSCertificate structure:
The version field SHALL be set to 2 to indicate v3 certificate.
The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256.
The issuer field SHALL be a sequence of RelativeDistinguishedName s.
The issuer field SHALL have exactly zero or one VendorID value present.
The subject field SHALL be a sequence of RelativeDistinguishedName s.
The subject field SHALL have exactly one VendorID value present.
If a VendorID value was present in the issuer field, the VendorID value found in subject
field SHALL match the value found in the issuer field.
The subject field SHALL have exactly zero or one ProductID value present.
The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1.
The certificate SHALL carry the following Extensions:
Basic Constraint extension SHALL be marked critical and have the cA field set to TRUE and
pathLen field set to 0.
Key Usage extension SHALL be marked critical and have the KeyUsage bitstring set to
keyCertSign | cRLSign.
Authority Key Identifier
Subject Key Identifier
The certificate MAY also carry the following additional Extensions:
Extended Key Usage
The PAI certificate presented in the following example is for the issuer of the example DAC certificate from the previous section.
-----BEGIN CERTIFICATE-----
MIIB1DCCAXqgAwIBAgIIPmzmUJrYQM0wCgYIKoZIzj0EAwIwMDEYMBYGA1UEAwwP TWF0dGVyIFRlc3QgUEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTAgFw0yMTA2Mjgx NDIzNDNaGA85OTk5MTIzMTIzNTk1OVowRjEYMBYGA1UEAwwPTWF0dGVyIFRlc3Qg UEFJMRQwEgYKKwYBBAGConwCAQwERkZGMTEUMBIGCisGAQQBgqJ8AgIMBDgwMDAw
WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASA3fEbIo8+MfY7z1eY2hRiOuu96C7z eO6tv7GP4avOMdCO1LIGBLbMxtm1+rZOfeEMt0vgF8nsFRYFbXDyzQsio2YwZDAS BgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQUr0K3
CU3r1RXsbs8zuBEVIl8yUogwHwYDVR0jBBgwFoAUav0idx9RH+y/FkGXZxDc3DGh cX4wCgYIKoZIzj0EAwIDSAAwRQIhAJbJyM8uAYhgBdj1vHLAe3X9mldpWsSRETET i+oDPOUDAiAlVJQ75X1T1sR199I+v8/CA2zSm6Y5PsfvrYcUq3GCGQ==
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIEZ7LYpps1z+a9sPw2qBp9jj5F0GLffNuCJY88hAHcMYoAoGCCqGSM49 AwEHoUQDQgAEgN3xGyKPPjH2O89XmNoUYjrrvegu83jurb+xj+GrzjHQjtSyBgS2 zMbZtfq2Tn3hDLdL4BfJ7BUWBW1w8s0LIg==
-----END EC PRIVATE KEY-----
Valid example PAI with associated private key, in X.509 PEM format
Human-readable contents of example PAI X.509 certificate
Certificate: Data:
Version: 3 (0x2)
Serial Number: 4498223361705918669 (0x3e6ce6509ad840cd) Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1
Validity
Not Before: Jun 28 14:23:43 2021 GMT
Not After : Dec 31 23:59:59 9999 GMT
Subject: CN = Matter Test PAI, 1.3.6.1.4.1.37244.2.1 = FFF1, 1.3.6.1.4.1.37244.2.2 = 8000
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:80:dd:f1:1b:22:8f:3e:31:f6:3b:cf:57:98:da:
14:62:3a:eb:bd:e8:2e:f3:78:ee:ad:bf:b1:8f:e1:
ab:ce:31:d0:8e:d4:b2:06:04:b6:cc:c6:d9:b5:fa:
b6:4e:7d:e1:0c:b7:4b:e0:17:c9:ec:15:16:05:6d: 70:f2:cd:0b:22
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:TRUE, pathlen:0
X509v3 Key Usage: critical Certificate Sign, CRL Sign
X509v3 Subject Key Identifier: AF:42:B7:09:4D:EB:D5:15:EC:6E:CF:33:B8:11:15:22:5F:32:52:88
X509v3 Authority Key Identifier: keyid:6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E
Signature Algorithm: ecdsa-with-SHA256 30:45:02:21:00:96:c9:c8:cf:2e:01:88:60:05:d8:f5:bc:72:
c0:7b:75:fd:9a:57:69:5a:c4:91:11:31:13:8b:ea:03:3c:e5:
03:02:20:25:54:94:3b:e5:7d:53:d6:c4:75:f7:d2:3e:bf:cf:
c2:03:6c:d2:9b:a6:39:3e:c7:ef:ad:87:14:ab:71:82:19
AlgorithmIdentifier, BIT STRING }
PAATBSCertificate,
Certificate ::= SEQUENCE { tbsCertificate signatureAlgorithm signatureValue
The attributes in a PAA certificate include:
PAATBSCertificate ::= SEQUENCE {
version INTEGER ( v3(2) ),
serialNumber INTEGER,
signature MatterSignatureIdentifier,
issuer Name,
validity Validity,
subject Name,
subjectPublicKeyInfo SEQUENCE {
algorithm OBJECT IDENTIFIER(id-x962-prime256v1), subjectPublicKey BIT STRING },
extensions PAAExtensions }
PAAExtensions ::= SEQUENCE {
basicConstraint Extension({extnID id-ce-basicConstraints, critical TRUE, extnValue BasicConstraints {cA TRUE, pathLen 1} }),
keyUsage Extension({extnID id-ce-keyUsage, critical TRUE, extnValue KeyUsage({keyCertSign}|{cRLSign})}),
authorityKeyIdentifier Extension({extnID id-ce-authorityKeyIdentifier}), subjectKeyIdentifier Extension({extnID id-ce-subjectKeyIdentifier}), extendedKeyUsage Extension({extnID id-ce-extKeyUsage}) OPTIONAL,
}
The PAA certificate SHALL follow the following constraints layered on top of the encoding specified by RFC 5280 within the TBSCertificate structure:
The version field SHALL be set to 2 to indicate v3 certificate.
The signature field SHALL contain the identifier for signatureAlgorithm ecdsa-with-SHA256.
The issuer field SHALL be a sequence of RelativeDistinguishedName s.
The issuer field SHALL have exactly zero or one VendorID value present.
The subject field SHALL be a sequence of RelativeDistinguishedName s.
The subject field SHALL have exactly zero or one VendorID value present.
The issuer and subject fields SHALL match exactly.
A ProductID value SHALL NOT be present in either the subject or issuer fields.
The algorithm field in subjectPublicKeyInfo field SHALL be the object identifier for prime256v1.
The certificate SHALL carry the following Extensions:
Basic Constraint extension SHALL be marked critical and have the cA field set to TRUE and have the pathLen field set to 1.
Key Usage extension SHALL be marked critical and have the KeyUsage bitstring set to
keyCertSign | cRLSign.
Authority Key Identifier
Subject Key Identifier
The certificate MAY also carry the following additional Extensions:
Extended Key Usage
The PAA certificate presented in the following example is for the issuer of the example PAI certificate from the previous section.
-----BEGIN CERTIFICATE-----
MIIBvTCCAWSgAwIBAgIITqjoMYLUHBwwCgYIKoZIzj0EAwIwMDEYMBYGA1UEAwwP TWF0dGVyIFRlc3QgUEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTAgFw0yMTA2Mjgx NDIzNDNaGA85OTk5MTIzMTIzNTk1OVowMDEYMBYGA1UEAwwPTWF0dGVyIFRlc3Qg UEFBMRQwEgYKKwYBBAGConwCAQwERkZGMTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABLbLY3KIfyko9brIGqnZOuJDHK2p154kL2UXfvnO2TKijs0Duq9qj8oYShpQ NUKWDUU/MD8fGUIddR6Pjxqam3WjZjBkMBIGA1UdEwEB/wQIMAYBAf8CAQEwDgYD VR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRq/SJ3H1Ef7L8WQZdnENzcMaFxfjAfBgNV
HSMEGDAWgBRq/SJ3H1Ef7L8WQZdnENzcMaFxfjAKBggqhkjOPQQDAgNHADBEAiBQ qoAC9NkyqaAFOPZTaK0P/8jvu8m+t9pWmDXPmqdRDgIgI7rI/g8j51RFtlM5CBpH mUkpxyqvChVI1A0DTVFLJd4=
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIGUSyuyuz8VD1gYjFhWXFi8BRoTFZaEpti/SjCerHMxQoAoGCCqGSM49 AwEHoUQDQgAEtstjcoh/KSj1usgaqdk64kMcranXniQvZRd++c7ZMqKOzQO6r2qP yhhKGlA1QpYNRT8wPx8ZQh11Ho+PGpqbdQ==
-----END EC PRIVATE KEY-----
Valid example PAA with associated private key, in X.509 PEM format
Human-readable contents of example PAA X.509 certificate
Certificate: Data:
Version: 3 (0x2)
Serial Number: 5668035430391749660 (0x4ea8e83182d41c1c) Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1
Validity
Not Before: Jun 28 14:23:43 2021 GMT
Not After : Dec 31 23:59:59 9999 GMT
Subject: CN = Matter Test PAA, 1.3.6.1.4.1.37244.2.1 = FFF1
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:b6:cb:63:72:88:7f:29:28:f5:ba:c8:1a:a9:d9:
3a:e2:43:1c:ad:a9:d7:9e:24:2f:65:17:7e:f9:ce:
d9:32:a2:8e:cd:03:ba:af:6a:8f:ca:18:4a:1a:50:
35:42:96:0d:45:3f:30:3f:1f:19:42:1d:75:1e:8f:
8f:1a:9a:9b:75
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:TRUE, pathlen:1
X509v3 Key Usage: critical Certificate Sign, CRL Sign
X509v3 Subject Key Identifier: 6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E
X509v3 Authority Key Identifier: keyid:6A:FD:22:77:1F:51:1F:EC:BF:16:41:97:67:10:DC:DC:31:A1:71:7E
Signature Algorithm: ecdsa-with-SHA256 30:44:02:20:50:aa:80:02:f4:d9:32:a9:a0:05:38:f6:53:68:
ad:0f:ff:c8:ef:bb:c9:be:b7:da:56:98:35:cf:9a:a7:51:0e:
02:20:23:ba:c8:fe:0f:23:e7:54:45:b6:53:39:08:1a:47:99:
49:29:c7:2a:af:0a:15:48:d4:0d:03:4d:51:4b:25:de
The device attestation procedure SHALL be executed by Commissioners when commissioning a device. It serves to validate whether a particular device is certified for Matter compliance and that it was legitimately produced by the certified manufacturer. See Section 5.5, “Commissioning Flows” for the possible outcomes based on whether the Device Attestation Procedure succeeds or fails to attest the device.
The Device Attestation Certificate Chain MAY be read at any time, either prior to or after receipt of the AttestationResponse. The Commissionee SHALL make the Certificate Chain available whenever requested using Section 11.18.7.3, “CertificateChainRequest Command”. If the Commissioner does
not already have this information, to proceed with the validation, it SHALL request the Commissionee’s Device Attestation Certificate Chain using Section 11.18.7.3, “CertificateChainRequest Command”.
The procedure is as follows:
The Commissioner SHALL generate a random 32 byte attestation nonce using Crypto_DRBG().
The Commissioner SHALL send the AttestationNonce to the Commissionee and request Attestation Information using Section 11.18.7.1, “AttestationRequest Command”.
The Commissionee SHALL return the signed Attestation Information to the Commissioner using Section 11.18.7.2, “AttestationResponse Command”.
After execution of the procedure, the Attestation Information SHOULD be validated using the checks described in Section 6.2.3.1, “Attestation Information Validation”.
A Commissioner validating the Attestation Information SHOULD record sufficient information to provide detailed results of the validation outcome to users. Therefore, prior to validating Attestation Information, a Commissioner SHOULD have previously obtained the Device Attestation Certificate chain for the Commissionee, so that the DAC and PAI necessary for the procedure are available.
In order to consider a Commissionee successfully attested, a Commissioner SHALL have successfully validated at least the following:
The PAA SHALL be validated for presence in the Commissioner’s trusted root store, which SHOULD include at least the set of globally trusted PAA certificates present in the Distributed Compliance Ledger at the issuing timestamp (notBefore) of the DAC.
The DAC certificate chain SHALL be validated using the Crypto_VerifyChainDER() function, taking into account the mandatory presence of the PAI and of the PAA.
Chain validation SHALL be performed with respect to the notBefore timestamp of the DAC to ensure that the DAC was valid when it was issued. This way of validating is abided by the Crypto_VerifyChainDER() function.
Chain validation SHALL include revocation checks of the DAC, PAI and PAA, based on the Commissioner’s best understanding of revoked entities.
The VendorID value found in the subject DN of the DAC SHALL match the VendorID value in the subject DN of the PAI certificate.
If the PAA certificate contains a VendorID value in its subject DN, its value SHALL match the VendorID value in the subject DN of the PAI certificate.
The Device Attestation Signature (attestation_signature) field from Attestation Response SHALL be validated:
Success = Crypto_Verify(
publicKey = Public key from DAC,
message = Attestation Information TBS (attestation_tbs), signature = Device Attestation Signature (attestation_signature)
)
where the fields are encoded as described in Section 11.18.5.5, “Attestation Information”.
The AttestationChallenge SHALL be obtained from a CASE session, resumed CASE session, or PASE session depending on the method used to establish the secure session within which device attestation is conducted.
The AttestationNonce in Device Attestation elements SHALL match the Commissioner’s provided AttestationNonce.
The Certification Declaration signature SHALL be validated using the Crypto_Verify()
function and the public key obtained from the CSA’s Certificate Authority Certificate.
The Certification Declaration SHALL be validated:
The vendor_id field in the Certification Declaration SHALL match the VendorID attribute found in the Basic Information cluster.
The product_id_array field in the Certification Declaration SHALL contain the value of the ProductID attribute found in the Basic Information cluster.
The Certification Declaration SHALL be considered valid only if it contains both or neither of the dac_origin_vendor_id and dac_origin_product_id fields.
If the Certification Declaration has both the dac_origin_vendor_id and the dac_origin_product_id
fields, the following validation SHALL be done:
The VendorID value from the subject DN in the DAC SHALL match the dac_origin_vendor_id
field in the Certification Declaration.
The VendorID value from the subject DN in the PAI SHALL match the dac_origin_vendor_id
field in the Certification Declaration.
The ProductID value from the subject DN in the DAC SHALL match the
dac_origin_product_id field in the Certification Declaration.
The ProductID value from the subject DN in the PAI, if such a ProductID value appears, SHALL match the dac_origin_product_id field in the Certification Declaration.
If the Certification Declaration has neither the dac_origin_vendor_id nor the
dac_origin_product_id fields, the following validation SHALL be done:
The VendorID value from the subject DN in the DAC SHALL match the vendor_id field in the Certification Declaration.
The VendorID value from the subject DN in the PAI SHALL match the vendor_id field in the Certification Declaration.
The ProductID value from the subject DN in the DAC SHALL be present in the
product_id_array field in the Certification Declaration.
The ProductID value from the subject DN in the PAI, if such a Product ID is present, SHALL
match one of the values present in the product_id_array field in the Certification Declaration.
If the Certification Declaration contains the authorized_paa_list field, the following validation SHALL be done:
The Subject Key Identifier (SKI) extension value of the PAA certificate, which is the root of trust of the DAC, SHALL be present as one of the values in the authorized_paa_list field.
The certificate_id field SHOULD match the CDCertificateID field found in the entry of the DeviceSoftwareCompliance schema in the Distributed Compliance Ledger where the entry’s VendorID, Product ID and SoftwareVersion field match the respective VendorID, ProductID and SoftwareVersion attributes values found in the Basic Information Cluster.
The firmware_information field in the Attestation Information, if present, SHALL match the content of an entry in the Distributed Compliance Ledger for the specific device as explained in Section 6.3.2, “Firmware Information”. If the Commissioner does not support Firmware Information validation, it MAY skip checking this match.
The order of execution of the above validation steps MAY be optimized by Commissioners. For example, if some validation steps are deemed by a Commissioner to make the remainder of the steps unnecessary because they have no chance of succeeding, then the validation steps could be ordered such that superfluous steps or rounds trips are omitted.
A Certification Declaration (CD) is a cryptographic document that allows a Matter device to assert its protocol compliance. It is encoded in a CMS format described in RFC 5652. Upon successful completion of certification by a device type, Connectivity Standards Alliance creates the CD for that device type so that it can be included in the device firmware by the manufacturer.
The Certification Declaration is a CMS-encoded single-signature envelope whose message is a TLV- encoded certification-elements structure with an anonymous tag:
security_level [5] : UNSIGNED INTEGER [ range 8-bits ] security_information [6] : UNSIGNED INTEGER [ range 16-bits ] version_number [7] : UNSIGNED INTEGER [ range 16-bits ] certification_type [8] : UNSIGNED INTEGER [ range 8-bits] dac_origin_vendor_id [9, optional] : UNSIGNED INTEGER [ range 16-bits ] dac_origin_product_id [10, optional] : UNSIGNED INTEGER [ range 16-bits ]
authorized_paa_list [11, optional] : ARRAY [ length 1..10 ] OF OCTET STRING [ length 20 ]
}
: UNSIGNED INTEGER [ range 16-bits ]
: ARRAY [ length 1..100 ] OF UNSIGNED INTEGER [ range 16-
: UNSIGNED INTEGER [ range 32-bits ]
: STRING [ length 19 ]
: UNSIGNED INTEGER [ range 16-bits ]
format_version [0]
vendor_id [1]
product_id_array [2] bits ]
device_type_id [3]
certificate_id [4]
certification-elements => STRUCTURE [ tag-order ]
{
Certification Elements TLV structure
cd_content =
{
format_version (0) = 1,
vendor_id (1) = <vendor_id>,
product_id_array (2) = <array of product_id values>, device_type_id (3) = <primary device type identifier>,
certificate_id (4) = <globally unique certificate ID issued by CSA>, security_level (5) = 0,
security_information (6) = 0,
version_number (7) = <version_number>, certification_type (8) = <certification_type>,
dac_origin_vendor_id (9) = <Vendor ID associated with the DAC, optional>, dac_origin_product_id (10) = <Product ID associated with the DAC, optional>, authorized_paa_list (11) = <array of PAA SKIs, optional>
}
The Certification Elements TLV is encoded with data to form a cd_content message to be signed.
The format_version field SHALL contain the value 1.
The vendor_id field SHALL contain the Vendor ID associated with the Certification Declaration.
The product_id_array field SHALL contain an array of a number of Product IDs which are covered by the same certification (e.g. certification by similarity). All other fields of a Certification Declaration apply to all products in this array.
The device_type_id field SHALL contain the device type identifier for the primary function of the device. For example, if device_type_id is 10 (0x000a), it would indicate that the device has a primary function of a Door Lock device type. See also the _T subtype in Section 4.3.1.3, “Commissioning
Subtypes”.
The device_type_id field in a given Certificate Declaration SHOULD match the device_type_id value in the DCL entries associated with the VendorID and ProductID combinations present in that Certification Declaration.
The certificate_id field SHALL contain a globally unique serial number allocated by the CSA for this Certification Declaration.
The security_level and security_information fields are reserved for future use and SHALL be ignored at read time, and set to zero at issuance time.
The version_number field SHALL contain a version number assigned by the CSA that matches the Vendor ID and Product ID used in a DeviceSoftwareVersionModel entry in the Distributed Compliance Ledger matching the certification record associated with the product presenting this CD. The value of the version_number is not meant to be interpreted by commissioners and SHALL be recorded as assigned.
The certification_type field SHALL contain the type of certification for this CD, interpreted according to the following table:
certification_type | meaning |
0 | used for development and test purposes |
1 | provisional - used for a device when going into certification testing, or to allow production and distribution to occur in parallel with certification (with potential software fixes yielding a higher SoftwareVersion which gets certification) |
2 | official - allocated after passing certification |
other values | reserved |
For details about the usage of the certification_type field in the Device Attestation Procedure, see failure of Device Attestation Procedure.
The dac_origin_vendor_id field, if present, SHALL contain the Vendor ID value expected to be found in the Device Attestation Certificate’s subject DN.
The dac_origin_product_id field, if present, SHALL contain the Product ID value expected to be found in the Device Attestation Certificate’s subject DN.
The dac_origin_vendor_id and dac_origin_product_id SHALL only be present together.
The use of the dac_origin_vendor_id and dac_origin_product_id fields allows for a target of the device attestation procedure to have a manufacturing provenance which differs from the entity that obtains the ultimate certification. If present, they tie a given Certification Declaration to an original manufacturer’s device attestation chain of trust, so that DACs MAY be issued at manufacturing time without a priori knowledge of the ultimate vendor.
The optional authorized_paa_list field, if present, SHALL contain a list of one or more Product Attestation Authority (PAA) which is/are authorized (by the device manufacturer) to sign the Product Attestation Intermediate (PAI) Certificate which signs the Device Attestation Certificate for a product carrying this Certificate Declaration. Each such PAA is identified by the Subject Key Identifier (SKI) extension value of its certificate.
Any context-specific tags not listed in the above schema for Certification Elements SHALL be reserved for future use, and SHALL be silently ignored if seen by a Commissioner which cannot understand them.
See Section 6.2.3, “Device Attestation Procedure” for more details about usage of the Certification Declaration fields.
SignerInfo ::= SEQUENCE {
version INTEGER ( v3(3) ), subjectKeyIdentifier OCTET STRING,
digestAlgorithm OBJECT IDENTIFIER sha256 (2.16.840.1.101.3.4.2.1),
signatureAlgorithm OBJECT IDENTIFIER ecdsa-with-SHA256 (1.2.840.10045.4.3.2), signature OCTET STRING }
OBJECT IDENTIFIER pkcs7-data (1.2.840.113549.1.7.1),
OCTET STRING cd_content }
OBJECT IDENTIFIER sha256 (2.16.840.1.101.3.4.2.1),
EncapsulatedContentInfo, SignerInfo }
EncapsulatedContentInfo ::= SEQUENCE { eContentType
eContent
INTEGER ( v3(3) ),
version digestAlgorithm encapContentInfo signerInfo
CertificationDeclaration ::= SEQUENCE {
Certification Declaration CMS ASN.1 Encoding Format
The Certification Declaration encoding rules:
The format SHALL only support CMS version v3.
The digestAlgorithm SHALL use the sha256 algorithm.
The signatureAlgorithm SHALL use the ecdsa-with-SHA256 (ECDSA with SHA256) and secp256r1
curve, as defined in Section 2.4.2 of SEC 2.
The eContentType SHALL use the pkcs7-data type.
The subjectKeyIdentifier SHALL contain the subject key identifier (SKI) of a well-known Connectivity Standards Alliance certificate, that was used to generate the signature. The format of the key identifiers supported is available as part of the Certification Policy.
Note that Certification Declarations SHALL NOT be generated by any Node, but rather, they SHALL be stored and transmitted to a Commissioner by a Commissionee during the conveyance of the Attestation Information in response to an Attestation Request command.
See Section F.1, “Certification Declaration CMS test vector” for a complete example of generating a
Certification Declaration.
Firmware Information is an optional component of the Device Attestation Information (see Section 6.2.3, “Device Attestation Procedure”).
Firmware Information MAY contain one or more Firmware Digests that correspond to the components in the firmware that have been measured and recorded during the boot process (e.g., bootloader, kernel, root filesystem, etc), and MAY contain other metadata. A Firmware Digest SHALL either represent a hash of the corresponding firmware layer or a hash of the signed manifest that was used to validate the corresponding firmware layer during secure boot. An implementation MAY choose to hash the measurements of all components into a single hash and include only that hash in Firmware Information.
A device MAY report Firmware Information containing its firmware digests only if it implements a secure subsystem that protects the device attestation private key and is able to securely collect and report firmware digests as shown in Figure 35, “Illustration of the measured boot process”. This process is known as "measured boot".
Ideally, the measured boot process SHOULD be rooted in silicon such as a boot ROM, similar to the secure boot process found in many systems-on-chip (SoCs). Since many SoCs and microcontrollers are unable to perform measured boot in hardware, the process SHOULD start at the earliest firmware component possible (for example, at the bootloader shown in the figure below). In this case, this firmware component is not measured and in fact, it is the root for measurement. Therefore, it SHALL be resistant to attacks compromising subsequent firmware components (e.g., the ROM must verify its authenticity (secure boot) or it may be placed in a locked partition at the factory that cannot be updated by software in the field).
Figure 35. Illustration of the measured boot process
The device secure subsystem SHALL use the device attestation private key to sign attestation- elements and NOCSR-elements. The device secure subsystem SHALL fill the attestation-elements fields using information compiled into its image or generated during the measured boot process.
The device secure subsystem SHALL validate all signing requests so that if the device software, but not its secure subsystem, gets compromised it cannot act as a signing oracle to sign Attestation Information Responses with fake Firmware Digests.
The firmware_information field in attestation-elements SHALL NOT be generated by devices that do not implement a separate secure subsystem, in software or hardware, which maintains and controls the use of the device attestation private key.
For devices that support secure boot, it is straightforward to add support for measured boot. Specifically, the hashes of the different firmware components that are already generated and verified sequentially during secure boot SHALL be collected and stored for reporting. Devices that do not support secure boot MAY implement measured boot by generating the hashes in software during the boot process implementing the root for measurement in the earliest firmware component.
If a device that chooses to send Firmware Digests and which supports an industry-standard measured boot architecture and which can generate signed firmware attestation reports, the secure subsystem in the device MAY validate the firmware attestation reports locally and SHALL report the raw firmware digests in attestation-elements so that the firmware_information field in attestation-elements has the same values in all devices of the same model that run the specific Software Image.
Firmware Digests SHALL NOT be reported by devices that implement a single firmware component in the boot chain, because there is nothing to measure and report subsequently, unless they have support for measured boot built in the device’s boot ROM.
Commissioners MAY use the reported firmware information to confirm that the firmware version is authorized to run on the device, that it has not been revoked, or that it does not contain known vulnerabilities. Commissioners and Administrators that choose to verify this information SHOULD refer to canonical databases, such as the Distributed Compliance Ledger (see Section 11.23, “Distributed Compliance Ledger”) to validate that the reported firmware information matches what is expected for an authorized Software Image associated with a given Certification Declaration. The firmware information, when validated, SHALL be validated as an opaque well-known octet string. Internal semantic validation MAY be applied for error-reporting, but the exact format is out of the scope of this specification.
In cases where a Commissioner or Administrator detects such an invalid or problematic firmware version, Commissioners and Administrators MAY, after consultation with the user, refuse to commission the device, provide it with operational credentials, or otherwise operate it, until the firmware has been updated, to avoid putting the user at risk from compromised software.
Below is an illustrative example of the Commissioner actions to validate the firmware information.
Retrieve the firmware_information field from attestation-elements
Retrieve all Distributed Compliance Ledger DeviceSoftwareVersionModel entries for the Commissionee’s Vendor ID and Product ID.
Verify that there is a valid, non-revoked, entry where the FirmwareInformation field exactly
matches the firmware_information field in attestation-elements.
If verification fails, report error to the user
If verification succeeds, proceed with device commissioning
Below is an example of the corresponding Device actions. For illustrative purposes, it is assumed that the device implements a secure subsystem that maintains the private device attestation key and signs attestation-elements using this key but it does not have direct hardware support for measure boot. This is expected to be the common case for many devices covered by this version of the specification. Consequently, the measurement process can only start from the bootloader shown in the figure above.
The device bootloader produces a measurement of the OS kernel using a supported hash algorithm from RFC 5912 and delivers it to the secure subsystem.
The secure subsystem receives the measurement and stores in a location inaccessible to the OS.
The OS kernel produces a hash of the root filesystem and delivers the measurement to the secure subsystem.
When the secure subsystem is asked to sign an attestation-elements structure using its private device attestation key, it generates two FirmwareDigests or one combined FirmwareDigest from these measurements, fills the firmware_information field in attestation-elements using these measurements, fills the CD blob compiled into the secure environment and signs the attestation- elements structure.
The Device Vendor is responsible to provide the FirmwareInformation field when a new Software Image entry is reported in the corresponding Distributed Compliance Ledger entry.
Below is an exemplary ASN.1 schema for an encoding scheme that could be used to encode firmware information.
Firmware Information encoding example
HashAlgorithm ::= SEQUENCE { id OBJECT IDENTIFIER,
params ANY OPTIONAL
}
FirmwareDigest ::= SEQUENCE { digestAlgorithm HashAlgorithm, digestHash OCTET STRING
}
FirmwareInformation ::= SEQUENCE { firmwareDigests SEQUENCE OF FirmwareDigest
}
-- Example HashAlgorithm id
id-sha256 OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) 1
}
-- Below is an example value for the above exemplary FirmwareInformation firmwareInformation FirmwareInformation ::= {
-- The firmwareDigests contain two values, for two separate components. firmwareDigests {
{
digestAlgorithm { id id-sha256
},
digestHash '00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF'H
},
{
digestAlgorithm { id id-sha256
},
digestHash '101112131415161718191A1B1C1D1E1F101112131415161718191A1B1C1D1E1F'H
}
}
}
30663031 300d0609 60864801 65030402 01050004 20001122 33445566 778899AA BBCCDDEE FF001122 33445566 778899AA BBCCDDEE FF303130 0D060960 86480165 03040201 05000420 10111213 14151617 18191A1B 1C1D1E1F 10111213 14151617
18191A1B 1C1D1E1F
The above example would yield the following DER-encoded octet string:
The Node Operational credentials are a collection of credentials to enable a Node to identify itself within a Fabric. The Node Operational credentials are distinct from the Device Attestation credentials. The Node Operational credentials are installed during Commissioning.
The Node Operational credentials include the following items:
Node Operational Key Pair
Node Operational Certificate (NOC)
Intermediate Certificate Authority (ICA) Certificate (optional)
Trusted Root Certificate Authority (CA) Certificate(s)
Each Node in a Fabric is identified with a Node Operational Identifier. In order to securely identify the Node, the Node Operational Identifier is bound to the Node Operational Public Key as both are contained within the signed NOC. The Node Operational Identifier is a constituent part of the subject field of the NOC, according to the rules described in Matter DN Encoding Rules. A connecting Node can attest to the validity of the Node Operational Public Key and the Node Operational Identifier in a received NOC because the NOC is signed by a CA that the connecting Node trusts. Used with Certificate Authenticated Session Establishment (CASE), these data provide the basis for secure communications on the Fabric.
Commands from the Node Operational Credentials Cluster are used to install and update Node Operational credentials.
A Node receives its initial set of Node Operational credentials through the AddNOC command when it is commissioned onto a Fabric by a Commissioner.
Once installed, Node Operational credentials MAY be updated by an Administrator with the appropriate privileges using the UpdateNOC command.
Once installed, Node Operational credentials MAY be removed by an Administrator with the appropriate privileges using the RemoveFabric command. The removal uses RemoveFabric, since the Fabric association for the given Node Operational credentials may underpin a variety of bindings and other fabric-scoped configuration, which would remain in an inconsistent state if the Node Operational credentials alone were removed, as opposed to the entire associated Fabric and data.
The Node Operational Identifier is used for Node discovery and network address resolution within a network segment. The FabricID portion of the Node Operational Identifier serves a scoping purpose to identify disjoint operational Fabrics within a given network segment. The NodeID portion of the Node Operational Identifier is the logical addressing identifier used:
within Message-layer messages for logical addressing (see Section 4.4, “Message Frame Format”)
within Data Model bindings to express data subscription relationships between Nodes (see System Model)
within Access Control List Entries to refer to individual Nodes as access control grantees (subjects) when CASE sessions are used for communication (see Access Control Cluster)
In addition to the FabricID and NodeID, a Node Operational Identifier MAY include at most three 32- bit CASEAuthenticatedTag (1.3.6.1.4.1.37244.1.6) attributes used to tag the operational identifier to implement access control based on CASE Authenticated Tags.
The Fabric ID is a 64-bit value that identifies the Fabric and is scoped to a particular Root CA. For example, two fabrics with the same Fabric ID are not equivalent unless their Root CA are the same. The Fabric ID MAY be chosen randomly or algorithmically but it SHALL be allocated uniquely within the set of all possible Fabric IDs for which a given Root CA will sign operational certificates. Before allocating the Fabric ID, the Commissioner SHOULD attempt to ensure that an existing Fabric is reused and joined, if any is applicable from the perspective of the Commissioner in the current commissioning context. The method used for determining local Fabric ID existence is vendor-specific.
The Node ID is a 64-bit value that identifies a Node within a Fabric. The Node ID MAY be chosen randomly or algorithmically but it SHALL be allocated uniquely within the Fabric before it is given to the Node or otherwise used. The Node ID SHALL be chosen, by a Commissioner, at the time of Node commissioning.
The uniqueness constraint for Fabric ID is only required to be ensured within the scope of the Root CA serving the Commissioner.
When a Fabric is removed, through the RemoveFabric command or through a factory reset, the Node Operational Identifier, and the FabricID and NodeID that comprise it, SHALL be permanently removed from the Node’s memory.
A Node Operational Key Pair, comprised of a Node Operational Public Key and a Node Operational Private Key, is created using the Crypto_GenerateKeypair function. A new Node Operational Key Pair is generated for each Commissioning Session in accordance with security requirements.
All certificates in the Node Operational credentials are X.509v3 certificates compliant with RFC 5280, encoded in such a way that they respect the constraints in the Operational_Certificate section. They may be encoded as X.509v3 certificates or Matter Operational Certificates ("Matter Certificates" thereafter). The signature field of a certificate SHALL be calculated using the X.509v3 encoding of the certificate.
The NOC SHALL be issued by either a Root CA trusted within the Fabric or by an Intermediate Certificate Authority (ICA) whose ICA certificate is directly issued by such a Root CA. The NOC is
bound to the Node Operational Key Pair through the Node Operational Credential Signing Request (NOCSR).
The validity period specifies the time period for which a NOC is valid. For constrained or sleepy devices that lack accurate time, enforcement of an NOC’s validity period MAY be omitted.
In the case where an intermediate CA (ICA) issues the NOC, the ICA certificate is used to attest to the validity of the NOC. The Root CA certificate associated with the issuer of the ICA certificate is used in turn to attest to the validity of the ICA certificate.
Each Node has one or more trusted Root CA certificates in its Node Operational credentials that it uses to verify ICA certificates and Node Operational Certificates presented by other Nodes, treating them as trust anchors as described in RFC 5280. A Root CA certificate is self-signed. They are not verified but rather trusted because they were provisioned by a trusted Commissioner.
In the case where a Root CA issues the NOC, the Root CA certificate is used to attest to the validity of the NOC.
The trusted Root CA certificates that a Device trusts when the Device is verifying operational certificates are those stored in the TrustedRootCertificates attribute of that Device’s Node Operational Credentials cluster.
A device MAY have Root CA certificates that it trusts for purposes other than for operational credential verification. These certificates SHALL NOT appear in any Node’s TrustedRootCertificates attribute of the Node Operational Credentials cluster. The certificates configured in that cluster SHALL only be added during the commissioning process by the Commissioner, or during root rotation operations by an Administrator already trusted by the Node. Nodes SHALL NOT modify the TrustedRootCertificates attribute outside of the processing of Node Operational Credentials cluster commands.
The figures below show the Node Operational Certificate hierarchies, with and without optional ICAC.
Figure 36. Node Operational Certificate PKI hierarchy with optional ICAC
Figure 37. Node Operational Certificate PKI hierarchy without optional ICAC
The following procedure is used by a Node to obtain an Operational Credential. This procedure is part of Commissioning.
After the Commissioner validates Device Attestation Information, the following procedure is used to generate a Node Operational Key Pair and obtain the NOCSR.
The Commissioner SHALL generate a random 32 byte nonce named CSRNonce using
Crypto_DRBG().
The Commissioner SHALL send the CSRNonce to the Node and request NOCSR Information using the CSRRequest Command.
The Node SHALL create a new candidate Node Operational Key Pair, using Crypto_GenerateKeyPair(), valid for the duration of the Fail-Safe Context currently in progress.
The Node SHOULD verify that the newly generated candidate Node Operational Key Pair does not match any other existing Node Operational Key Pair on the device. If such a key collision was to be found, it would indicate a key pair that was not properly randomly generated. The procedure SHALL fail if such a collision is detected. See Section 11.18.7.5, “CSRRequest Command” for the error generated in that situation.
The candidate Node Operational Key Pair SHALL only be committed to persistent storage upon successful execution of the next AddNOC Command executed with a Node Operational Certificate whose public key matches the candidate key.
The Node SHALL create a Certificate Signing Request (CSR) by following the format and procedure in PKCS #10, which includes a signature using the Node Operational Private Key (see RFC 2986 section 4.2).
The CSR’s subject MAY be any value and the device SHOULD NOT expect the final operational certificate to contain any of the CSR’s subject DN attributes.
The Node SHALL generate and return the NOCSR Information (see Section 11.18.5.7, “NOCSR Information” for encoding) to the Commissioner using the CSRResponse Command. The NOCSR Information includes a signature using the Device Attestation Private Key.
Node Operational CSR Information Validation
Success = Crypto_Verify(
publicKey = Public key from DAC,
message = NOCSR Information TBS (nocsr_tbs),
signature = Device Attestation Signature (attestation_signature)
)
The Commissioner SHALL validate the Device Attestation Signature (attestation_signature) field from CSRResponse Command:
where the fields are encoded as described in Section 11.18.5.7, “NOCSR Information”.
The AttestationChallenge SHALL be obtained from a CASE session, resumed CASE session, or PASE session depending on the method used to establish the secure session within which device attestation is conducted.
The CSR Nonce in NOCSR Information SHALL match the Commissioner’s CSR Nonce.
The inner signature in the PKCS#10 csr sub-field of the CSRResponse Command's NOCSRElements
field SHALL be verified, per the definition of CSR signatures in PKCS #10.
Figure 38. Node Operational Credentials flow
A Node creates a NOCSR in response to the Commissioner, so that the Commissioner can request a NOC on the Node’s behalf from its trusted Certificate Authority. The CSR itself SHALL follow the encoding and rules from PKCS #10, with the minimum attributes shown in the example below.
Note that the subject field MAY be any value.
Certificate Request: Data:
Version: 1 (0x0) Subject: ...............
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:12:3b:90:f5:.......
ASN1 OID: prime256v1 NIST CURVE: P-256
Attributes:
Requested Extensions:
Signature Algorithm: ecdsa-with-SHA256 30:46:02:21:00:95:ff:......
NOCSR
A NOC can be renewed by an Administrator (a Node that has Administer privileges on the Node to be updated). The Administrator triggers the process by sending an CSRRequest Command.
A Node’s access to other Nodes can be revoked by removing the associated Node ID from Access Control Entry subjects where it appears. This action is taken by an Administrator which has the privilege to update the Access Control Cluster for its Nodes.
A NOC is a Node’s credential to operate on a Fabric. It SHALL be protected against the following threats:
The Node Operational Private Key SHALL be protected from unauthorized access.
The Node Operational Private Key SHOULD never leave the device.
The NOC SHALL NOT contain information that may violate the user’s privacy.
The NOC SHALL be wiped if the Node is factory reset.
This section details the Matter certificate data structure (hereafter "Matter certificate"), a specific encoding that is sometimes used as a compact alternative to the standard X.509 certificate format [RFC 5280] for bandwidth-efficient transmission. A Node Operational Certificate (NOC), Intermediate CA certificate and Root CA certificate MAY all be encoded as a Matter certificate.
To compress the structure more efficiently than an X.509 certificate, a Matter certificate SHALL be encoded with the Matter TLV structured data interchange language [Appendix A, Tag-length-value (TLV) Encoding Format] instead of the ASN.1 Distinguished Encoding Rules (DER) [X.690].
This section provides a technical specification of the structure of data comprising a Matter certificate with accompanying requirements for their semantic validation, and their conversion to and from X.509 certificates. In some cases, as noted, the limitations on the semantic interpretation of parts of a Matter certificate follow from limitations applied by [RFC 5280].
Certificate Text Version Number Serial Number
Signature Algorithm ID Issuer Name
Validity period Not Before Not After
Subject name
Subject Public Key Info Public Key Algorithm Subject Public Key
Issuer Unique Identifier Subject Unique Identifier Extensions
Certificate Signature Algorithm Certificate Signature
A certificate comprises a record of the following conceptual fields:
Several important components of X.509 certificates follow the pattern commonly used in ASN.1 data models where some types are constructed with an ASN.1 object identifier (OID) to identify each variant. For example, the cryptographic algorithm used in the digital signature is identified by its OID.
Matter certificates do not use ASN.1 OIDs. Instead, each valid ASN.1 OID SHALL be mapped to a Matter TLV tag within its reference category. Each reference category defines the context of the Matter tag, and tag values are assigned to the reference categories according to the type of fields where they can appear in X.509 certificates.
A Matter certificate encodes a subset of the object identifiers (OIDs) specified in X.509. Only some attribute types for relative distinguished names are valid, only certain cryptographic algorithms (corresponding to the algorithms as defined in Chapter 3, Cryptographic Primitives) are used, and only a limited set of extensions are used. Therefore, every Matter certificate can be represented as a corresponding X.509 certificate. However, the converse is not true; not every X.509 certificate can be represented as a Matter certificate.
}
: LIST [ length 1.. ] OF dn-attribute,
: public-key-algorithm,
: elliptic-curve-id,
: OCTET STRING,
: LIST [ length 1.. ] OF extension,
: ec-signature,
: OCTET STRING [ length 0..20 ],
: signature-algorithm,
: LIST [ length 1.. ] OF dn-attribute,
: UNSIGNED INTEGER [ range 32-bits ],
: UNSIGNED INTEGER [ range 32-bits ],
serial-num [1]
sig-algo [2]
issuer [3]
not-before [4]
not-after [5]
subject [6]
pub-key-algo [7]
ec-curve-id [8]
ec-pub-key [9]
extensions [10]
signature [11]
matter-certificate [anonymous] => STRUCTURE [tag-order]
{
The signature included in a Matter certificate is the signatureValue of the corresponding X.509 certificate, not a signature of the preceding Matter TLV data in the Matter certificate structure. Accordingly, validating the signature in a Matter certificate entails its logical conversion to the corresponding X.509 certificate to recover the original tbsCertificate of the basic syntax signed by the Certificate Authority (CA).
Matter certificates SHALL only support version X.509 v3. This field is not encoded in the Matter certificate structure.
The context-specific tag serial-num [1] SHALL be used to identify the serial number field in the Matter certificate structure.
A Matter certificate follows the same limitation on admissible serial numbers as in [RFC 5280], i.e., that implementations SHALL admit serial numbers up to 20 octets in length, and certificate authorities SHALL NOT use serial numbers longer than 20 octets in length.
Like an X.509 certificate, a Matter certificate SHALL include a digital signature in its signature component. The signature algorithm component of a Matter certificate specifies the cryptographic algorithm used for composing and validating the signature embedded in the signature component of the certificate. The signature algorithm SHALL match the algorithm in Section 3.5.3, “Signature and verification”.
The context-specific tag sig-algo [2] SHALL be used to identify the signature algorithm field in the Matter certificate structure.
signature-algorithm => UNSIGNED INTEGER [ range 8-bits ]
{
ecdsa-with-sha256 = 1,
}
The following values SHALL be defined for signature-algorithm:
Table 55. Signature Algorithm Object Identifiers
Value | ASN.1 OID |
1 | iso(1) member-body(2) us(840) ansi-x962(10045) signatures(4) ecdsa-with-SHA2(3) ecdsa- with-SHA256(2) |
The context-specific tags issuer [3] and subject [6] SHALL be used to identify the issuer and the subject DN fields in the Matter certificate structure. The entries in the lists SHALL be Distinguished Names (DNs), which are described in Section 6.5.6.1, “X.501 Distinguished Names”.
The Issuer Name and Subject Name components of an X.509 certificate contain DNs as defined in [RFC 5280]. The ASN.1 format of a DN is a sequence of Relative Distinguished Names (RDNs). Two distinguished names DN1 and DN2 match if they have the same number of RDNs, for each RDN in DN1 there is a matching RDN in DN2, and the matching RDNs appear in the same order in both DNs.
The RDN in an X.509 certificate may be encoded as a set of one or more DN attributes, although in practice it is usually a single DN attribute. The RDN in a Matter certificate SHALL be always a single DN attribute. Two relative distinguished names RDN1 and RDN2 match if the attribute in RDN1 matches the attribute in RDN2.
dn-attribute => CHOICE OF
{
// Standard and Matter-specific DN attributes.
// Of these, all are encoded as UTF8String except domain-component,
// which is encoded as IA5String in X.509 form. common-name [1] : STRING,
surname [2] : STRING,
serial-num [3] : STRING,
country-name [4] : STRING,
locality-name [5] : STRING, state-or-province-name [6] : STRING, org-name [7] : STRING,
org-unit-name [8] : STRING,
title [9] : STRING,
name [10] : STRING,
given-name [11] : STRING,
initials [12] : STRING,
gen-qualifier [13] : STRING,
dn-qualifier [14] : STRING,
pseudonym [15] : STRING,
domain-component [16] : STRING,
matter-node-id [17] : UNSIGNED INTEGER, matter-firmware-signing-id [18] : UNSIGNED INTEGER, matter-icac-id [19] : UNSIGNED INTEGER,
matter-rcac-id [20] : UNSIGNED INTEGER,
matter-fabric-id [21] : UNSIGNED INTEGER,
matter-noc-cat [22] : UNSIGNED INTEGER,
// Standard DN attributes when encoded as PrintableString in X.509 form
// NOTE: The tags for these SHALL be the base tags + 0x80. common-name-ps [129] : STRING,
surname-ps [130] : STRING,
serial-num-ps [131] : STRING,
country-name-ps [132] : STRING,
locality-name-ps [133] : STRING, state-or-province-name-ps [134] : STRING, org-name-ps [135] : STRING,
org-unit-name-ps [136] : STRING,
title-ps [137] : STRING,
name-ps [138] : STRING,
given-name-ps [139] : STRING,
initials-ps [140] : STRING,
gen-qualifier-ps [141] : STRING,
dn-qualifier-ps [142] : STRING,
pseudonym-ps [143] : STRING,
}
Table 56, “Standard DN Object Identifiers” lists the context-specific tags defined for the standard DN attribute types used in Matter that can be encoded in X.509 certificates as either UTF8String or as
PrintableString format. In Matter certificates, the context-specific tag is logically-ORed with 0x80 (and its name given a corresponding -ps suffix) to indicate that the corresponding X.509 encoding of the attribute uses the PrintableString format instead of UTF8String.
Table 56. Standard DN Object Identifiers
Tag base | Matter name base | ASN.1 OID |
1 | common-name | joint_iso_ccitt(2) ds(5) attributeType(4) commonName(3) |
2 | surname | joint_iso_ccitt(2) ds(5) attributeType(4) surname(4) |
3 | serial-num | joint_iso_ccitt(2) ds(5) attributeType(4) serialNumber(5) |
4 | country-name | joint_iso_ccitt(2) ds(5) attributeType(4) countryName(6) |
5 | locality-name | joint_iso_ccitt(2) ds(5) attributeType(4) localityName(7) |
6 | state-or-province-name | joint_iso_ccitt(2) ds(5) attributeType(4) stateOrProvinceName(8) |
7 | org-name | joint_iso_ccitt(2) ds(5) attributeType(4) organizationName(10) |
8 | org-unit-name | joint_iso_ccitt(2) ds(5) attributeType(4) organizationalUnitName(11) |
9 | title | joint_iso_ccitt(2) ds(5) attributeType(4) title(12) |
10 | name | joint_iso_ccitt(2) ds(5) attributeType(4) name(41) |
11 | given-name | joint_iso_ccitt(2) ds(5) attributeType(4) givenName(42) |
12 | initials | joint_iso_ccitt(2) ds(5) attributeType(4) initials(43) |
13 | gen-qualifier | joint_iso_ccitt(2) ds(5) attributeType(4) generationQualifier(44) |
14 | dn-qualifier | joint_iso_ccitt(2) ds(5) attributeType(4) dnQualifier(46) |
15 | pseudonym | joint_iso_ccitt(2) ds(5) attributeType(4) pseudonym(65) |
Table 57, “Standard DN Domain Component Object Identifier” lists the context-specific tag defined for the standard DN attribute type used in Matter that is encoded in X.509 certificates as IA5String.
Table 57. Standard DN Domain Component Object Identifier
Tag | Matter name | ASN.1 OID |
16 | domain-component | itu_t(0) data(9) pss(2342) ucl(19200300) pilot(100) pilotAttributeType(1) domainComponent(25) |
In addition to the standard DN attribute types, there are Matter-specific DN attribute types under the 1.3.6.1.4.1.1.37244 private arc. See Section 6.1.1, “Encoding of Matter-specific RDNs” for
constraints and examples related to usage of Matter-specific DN attribute types.
The Matter-specific DN attribute types convey information about Matter-specific certificate types as listed in Table 58, “Matter Certificate Types”.
Table 58. Matter Certificate Types
Matter name | Description |
matter-node-id | Certifies the identity of a Matter Node Operational Certificate (NOC). |
matter-firmware-signing-id | Certifies the identity of a firmware signing certificate. |
matter-icac-id | Certifies the identity of a Matter Intermediate CA (ICA) Certificate. |
matter-rcac-id | Certifies the identity of a Matter Root CA Certificate. |
The value of matter-icac-id and matter-rcac-id DN attribute types MAY be any 64-bit identifier desired by the certificate’s issuer. Apart from marking what type of certificates are involved, they MAY be used for debugging purposes to determine the specific CA in use, for example if different production tiers or regions are used.
The rules that SHALL be followed for Matter-specific attribute types when encoding the subject DN are:
For a Matter Node Operational Certificate (NOC):
The subject DN SHALL encode exactly one matter-node-id attribute.
The matter-node-id attribute’s value SHALL be in the Operational Node ID range (0x0000_0000_0000_0001 to 0xFFFF_FFEF_FFFF_FFFF), see Table 4, “Node Identifier Allocations”.
The subject DN SHALL encode exactly one matter-fabric-id attribute.
The matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fabric References and Fabric Identifier”).
The subject DN SHALL NOT encode any matter-icac-id attribute.
The subject DN SHALL NOT encode any matter-rcac-id attribute.
The subject DN MAY encode at most three matter-noc-cat attributes.
Each matter-noc-cat attribute present, if any, SHALL encode a different CASE Authenticated Tag identifier (upper 16 bits of value) than is used by other matter-noc-cat attributes (CATs).
For a Matter ICA Certificate:
The subject DN SHALL NOT encode any matter-node-id attribute.
The subject DN MAY encode at most one matter-fabric-id attribute.
If present, the matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fabric References and Fabric Identifier”).
The subject DN MAY encode at most one matter-icac-id attribute.
The subject DN SHALL NOT encode any matter-rcac-id attribute.
The subject DN SHALL NOT encode any matter-noc-cat attribute.
For a Matter Root CA Certificate:
The subject DN SHALL NOT encode any matter-node-id attribute.
The subject DN MAY encode at most one matter-fabric-id attribute.
If present, the matter-fabric-id attribute’s value SHALL NOT be 0 (see Section 2.5.1, “Fabric References and Fabric Identifier”).
The subject DN SHALL NOT encode any matter-icac-id attribute.
The subject DN MAY encode at most one matter-rcac-id attribute.
The subject DN SHALL NOT encode any matter-noc-cat attribute.
The attributes SHALL appear in the same order in the Matter certificate and in the corresponding X.509 certificates.
When any matter-fabric-id attributes are present in either the Matter Root CA Certificate or the Matter ICA Certificate, the value SHALL match the one present in the Matter Node Operational Certificate (NOC) within the same certificate chain.
The order of the attributes can be issuer-specific and is not enforced by Matter specifications.
All implementations SHALL accept, parse, and handle Matter certificates with up to 5 RDNs in a single DN.
All implementations SHALL reject Matter certificates with more than 5 RDNs in a single DN.
In addition to the above rules, the encoding constraints in Section 6.1.1, “Encoding of Matter- specific RDNs” SHALL be followed.
subject = [[
matter-node-id = 0x0102030405060708U, matter-fabric-id = 0xFAB000000000001DU
]]
The following is an example of subject DN encoding for a Matter Node Operational Certificate (NOC). Typically, it is a list of two RDN attributes:
In addition to the mandatory attributes, it may also encode other supported RDN attributes such as
common-name and CASE Authenticated Tags as presented below:
]]
matter-node-id = 0x0102030405060708U, matter-fabric-id = 0xFAB000000000001DU, matter-noc-cat = 0xABCD0002U
= "NOC Example",
subject = [[
common-name
subject = [[
matter-noc-cat = 0xABCD0004U,
matter-node-id = 0x0102030405060708U, matter-noc-cat = 0xABCE0018U,
matter-fabric-id = 0xFAB000000000001DU, matter-noc-cat = 0xABCF0002U
]]
The following subject DN example illustrates that multiple RDN attributes of the same type can be encoded. The specific order of attributes is not enforced. Note that number of RDN attributes in the subject field SHALL NOT exceed five:
subject = [[
matter-node-id = 0x0102030405060708U, matter-fabric-id = 0xFAB000000000001DU,
matter-noc-cat = 0xABCD0004U, # <-- Value 0xABCD, Version 0x0004 matter-noc-cat = 0xABCD0002U, # <-- Value 0xABCD, Version 0x0002
]]
The following example illustrates an illegal subject DN due to the presence of the same CASE Authenticated Tag value with two different version numbers.
subject = [[
matter-rcac-id = 0xCA0000000000001DU
]]
The following is an example of subject DN encoding for a Matter Root CA certificate. In this case, the Matter Root CA certificate is not associated with a specific Matter fabric:
The following is another example of subject DN encoding for a Matter Root CA certificate. In this case, the Matter Root CA certificate is associated with a specific Matter fabric. This DN also encodes an issuer-specific common-name RDN attribute:
subject = [[
matter-rcac-id = 0xCA0000000000001DU, matter-fabric-id = 0xFAB000000000001DU, common-name = "ROOT CA HOME 3"
]]
The context-specific tags not-before [4] and not-after [5] SHALL be used to identify the not-before and not-after fields in the Matter certificate structure, which indicate the period of validity for the certificate. These two fields SHALL be encoded as unsigned integers. The value of these fields SHALL be encoded as a UTC time of type epoch-s (Epoch Time in Seconds).
Special value 0, when encoded in the not-after field, corresponds to the X.509/RFC 5280 defined special time value 99991231235959Z meaning no well-defined expiration date.
public-key-algorithm => UNSIGNED INTEGER [ range 8-bits ]
{
ec-pub-key = 1,
}
The context-specific tag pub-key-algo [7] SHALL be used to identify the public key algorithm field in the Matter certificate structure.
The following values SHALL be defined for public-key-algorithm:
Table 59. Public Key Algorithm Object Identifiers
Value | ASN.1 OID |
1 | iso(1) member-body(2) us(840) ansi-x962(10045) keyType(2) ecPublicKey(1) |
elliptic-curve-id => UNSIGNED INTEGER [ range 8-bits ]
{
prime256v1 = 1,
}
The context-specific tag ec-curve-id [8] SHALL be used to identify the elliptic curve field in the Matter certificate structure.
The following values SHALL be defined for elliptic-curve-id:
Table 60. Elliptic Curve Object Identifiers
Value | ASN.1 OID |
1 | iso(1) member_body(2) us(840) ansi-x962(10045) curves(3) prime(1) prime256v1(7) |
The context-specific tag ec-pub-key [9] SHALL be used to identify the elliptic curve public key material field in the Matter certificate structure. The public key SHALL be a byte string representation of an uncompressed elliptic curve point as defined in section 2.3.3 of SEC1.
: basic-constraints,
: UNSIGNED INTEGER [ range 16-bits ],
: ARRAY [ length 1.. ] OF key-purpose-id,
: OCTET STRING [ length 20 ],
: OCTET STRING [ length 20 ],
: OCTET STRING,
extension => CHOICE OF
{
basic-cnstr [1]
key-usage [2]
extended-key-usage [3]
subject-key-id [4]
authority-key-id [5]
future-extension [6]
}
The context-specific tag extensions [10] SHALL be used to identify the extensions field in the Matter certificate structure. The extensions list SHALL NOT contain more than one instance of a particular extension. The following table summarizes context-specific tags defined for the certificate extension types used in Matter.
Table 61. Extensions Object Identifiers
Tag | Matter Name | ASN.1 OID |
1 | basic-cnstr | joint-iso-itu-t(2) ds(5) certificateExtension(29) basicConstraints(19) |
2 | key-usage | joint-iso-itu-t(2) ds(5) certificateExtension(29) keyUsage(15) |
3 | extended-key-usage | joint-iso-itu-t(2) ds(5) certificateExtension(29) extendedKeyUsage(37) |
4 | subject-key-id | joint-iso-itu-t(2) ds(5) certificateExtension(29) subjectKeyIdentifier(14) |
5 | authority-key-id | joint-iso-itu-t(2) ds(5) certificateExtension(29) authorityKeyIdentifier(35) |
6 | future-extension | any valid ASN.1 OID (future extension) |
These context-specific tags identify the extension entries in the extensions list. The type of each extension is further described in the subsections below.
The basic constraints extension identifies whether the subject of the certificate is a CA and the maximum depth of valid certification paths that include this certificate.
When present, the basic constraints extension SHALL be treated as critical and it SHALL be marked as critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the Matter certificate structure.
basic-constraints => STRUCTURE [tag-order]
{
is-ca [1] : BOOLEAN,
path-len-constraint [2, optional] : UNSIGNED INTEGER [ range 8-bits ],
}
The context-specific tag basic-cnstr [1] SHALL be used to identify a basic constraints extension entry in the Matter certificate extensions list.
The is-ca field SHALL be encoded regardless of the value (true or false). The path-len-constraint
MAY be present only when is-ca == true.
The key usage extension defines the purpose of the key contained in the certificate.
When present, the key usage extension SHALL be treated as critical and it SHALL be marked as critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the Matter certificate structure.
The context-specific tag number key-usage [2] SHALL be used to identify a key usage extension entry in the Matter certificate extensions list.
key-usage-flag => UNSIGNED INTEGER [ range 16-bits ]
{
digitalSignature = 0x0001, nonRepudiation = 0x0002, keyEncipherment = 0x0004, dataEncipherment = 0x0008, keyAgreement = 0x0010,
keyCertSign = 0x0020,
CRLSign = 0x0040,
encipherOnly = 0x0080,
decipherOnly = 0x0100,
}
The key-usage field is derived as a logical OR of all key-usage-flag values that apply to the corresponding public key:
The extended key usage extension indicates one or more purposes for which the certified public key may be used, in addition to or in place of the basic purposes indicated in the key usage extension.
When present, the extended key usage extension SHALL be treated as critical and it SHALL be marked as critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the Matter certificate structure.
The context-specific tag number extended-key-usage [3] SHALL be used to identify an extended key usage extension entry in the Matter certificate extensions list.
The extended-key-usage field SHALL be encoded as an array of key-purpose-id values, where each
key-purpose-id => UNSIGNED INTEGER [ range 8-bits ]
key-purpose-id value SHALL be encoded as 8-bit unsigned integer:
The following values SHALL be defined for key-purpose-id:
Table 62. Key Purpose Object Identifiers
Value | ASN.1 OID |
1 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, serverAuth(1) |
2 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, clientAuth(2) |
3 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, codeSigning(3) |
4 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, emailProtection(4) |
5 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, timeStamping(8) |
6 | iso(1), organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), 3, OCSPSigning(9) |
The key-purpose-id values in the extended-key-usage array SHALL be encoded in the same order as they appeared in the corresponding X.509 certificate.
The subject key identifier extension provides a means of identifying Matter certificates that contain a particular public key.
When present, the subject key identifier extension SHALL be treated as non-critical and it SHALL be marked as non-critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the Matter certificate structure.
The context-specific tag number subject-key-id [4] SHALL be used to identify a subject key identifier extension entry in the Matter certificate extensions list.
The Subject Key Identifier field SHALL be derived from the public key using method (1) described in section 4.2.1.2 of [RFC 5280]. Thus, the subject-key-id SHALL be composed of the 160-bit SHA-1 hash of the certificate’s subject public key value.
See Section 6.1.2, “Key Identifier Extension Constraints” for additional constraints.
The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a Matter certificate.
When present, the authority key identifier extension SHALL be treated as non-critical and it SHALL be marked as non-critical in the corresponding X.509 certificate. The critical field SHALL NOT be encoded in the Matter certificate structure.
The context-specific tag number authority-key-id [5] SHALL be used to identify an authority key identifier extension entry in the Matter certificate extensions list.
Note that the authority key identifier extension field in an X.509 certificate may optionally include issuer and serial number fields, which are not supported by Matter certificates.
The Authority Key Identifier field SHALL be derived from the public key using method (1) described in section 4.2.1.2 of [RFC 5280]. Thus, the authority-key-id SHALL be composed of the 160-bit SHA-1 hash of the public key used to verify the certificate’s signature.
See Section 6.1.2, “Key Identifier Extension Constraints” for additional constraints.
The Matter certificate is designed with extensibility in mind and this field is added to support arbitrary certificate extension in the future.
Note that implementations that do not support specific future extension will ignore it but will be able to use it for the Matter certificate signature validation. If ignored extension is marked as critical then validation of the corresponding Matter certificate SHALL fail.
The context-specific tag number future-extension [6] SHALL be used to identify all future extension entries in the Matter certificate extensions list. There MAY be more than one future extension field.
The future-extension field SHALL be encoded as OCTET STRING and it SHALL be an exact copy of the DER encoded extension field (including the DER encoded ASN.1 OID of the extension) in the corresponding X.509 certificate. These extension fields in a Matter certificate SHALL be encoded in the same order as they appeared in the original X.509 certificate.
The rules that SHALL be followed when encoding the Matter certificate are:
For a Matter Node Operational Certificate (NOC):
The basic constraints extension SHALL be encoded with is-ca set to false.
The key usage extension SHALL be encoded with exactly one flag: digitalSignature.
The extended key usage extension SHALL be encoded with exactly two key-purpose-id values: serverAuth and clientAuth.
The subject key identifier extension SHALL be present.
The authority key identifier extension SHALL be present.
For Matter ICA Certificate and Matter Root CA Certificate:
The basic constraints extension SHALL be encoded with is-ca set to true.
The key usage extension SHALL be encoded with exactly two flags: keyCertSign and CRLSign.
The extended key usage extension SHALL NOT be present.
The subject key identifier extension SHALL be present.
The authority key identifier extension SHALL be present.
For the Matter Root CA Certificate the authority key identifier extension SHALL be equal to the subject key identifier extension.
For a Matter Firmware Signing Certificate these rules SHALL be followed:
The basic constraints extension SHALL be encoded with is-ca set to false.
The key usage extension SHALL be encoded with exactly one flag: digitalSignature.
The extended key usage extension SHALL be encoded with exactly one key-purpose-id values: codeSigning.
The subject key identifier extension SHALL be present.
The authority key identifier extension SHALL be present.
The extensions SHALL appear in the same order in the Matter certificate and in the corresponding X.509 certificates.
Note that Matter doesn’t specify how firmware images are signed and implementation of firmware image signing is manufacturer-specific. However, since firmware image signing is a common feature, the format for Matter TLV certificates has affordances for encoding firmware signing certificates.
The context-specific tag signature [11] SHALL be used to identify the signature field in the Matter certificate structure.
ec-signature => OCTET STRING [ length (CRYPTO_GROUP_SIZE_BYTES * 2) ]
An ec-signature is the encoding of the signature as defined in Section 3.5.3, “Signature and verification”.
The Matter certificate is considered invalid if it violates Matter certificate encoding rules defined in this section. The processing of invalid Matter certificate SHOULD fail and an error SHOULD be reported to the application. Here is a non-exhaustive list of errors that may invalidate the certificate:
Matter certificate structure includes elements that are not defined in this section.
Matter certificate elements are encoded in a wrong order.
Matter certificate element has wrong type.
Length of an element is outside of its valid range, for example:
serial-num field is longer than 20 octets.
not-before or not-after field is longer than 32-bits.
subject-key-id or authority-key-id field is different from 20 octets.
Matter OID values encoded in Matter certificate are not defined in this section, for example:
sig-algo field encodes value, which is not defined in Table 55, “Signature Algorithm Object Identifiers”.
pub-key-algo field encodes value, which is not defined in Table 59, “Public Key Algorithm Object Identifiers”.
ec-curve-id field encodes value, which is not defined in Table 60, “Elliptic Curve Object Identifiers”.
key-purpose-id field of the Extended Key Usage Extension encodes value, which is not defined in Table 62, “Key Purpose Object Identifiers”.
Invalid Matter Distinguished Names encoding for Issuer and Subject DNs. Refer to Section 6.5.6.3, “Matter DN Encoding Rules” for more details. For example:
Node Subject DN doesn’t include Matter specific matter-node-id or matter-fabric-id
attribute.
Firmware signing Subject DN doesn’t include Matter specific matter-firmware-signing-id
attribute.
Intermediate CA Subject DN doesn’t include Matter specific matter-icac-id attribute.
Root CA Subject DN doesn’t include Matter specific matter-rcac-id attribute.
Certificate Subject DN encodes matter-node-id and matter-rcac-id, which contradict each other.
Multiple matter-cat-id with the same identifier value and different version numbers, or any
matter-cat-id with a version number of 0.
CA certificate doesn’t have Basic Constraints Extension is-ca field set to 'true'.
key-usage field of the Key Usage Extension has undefined flags.
Certificate extension that SHALL be marked as critical is marked as non-critical in the X.509 representation and vise versa.
The same RCAC in X.509 and Matter TLV formats is presented in this section.
-----BEGIN CERTIFICATE-----
MIIBnTCCAUOgAwIBAgIIWeqmMpR/VBwwCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB gqJ8AQQMEENBQ0FDQUNBMDAwMDAwMDEwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 MTQyMzQyWjAiMSAwHgYKKwYBBAGConwBBAwQQ0FDQUNBQ0EwMDAwMDAwMTBZMBMG ByqGSM49AgEGCCqGSM49AwEHA0IABBNTo7PvHacIxJCASAFOQH1ZkM4ivE6zPppa
yyWoVgPrptzYITZmpORPWsoT63Z/r6fc3dwzQR+CowtUPdHSS6ijYzBhMA8GA1Ud EwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQTr4GrNzdLLtKp ZJsSt6OkKH4VHTAfBgNVHSMEGDAWgBQTr4GrNzdLLtKpZJsSt6OkKH4VHTAKBggq
hkjOPQQDAgNIADBFAiBFgWRGbI8ZWrwKu3xstaJ6g/QdN/jVO+7FIKvSoNoFCQIh ALinwlwELjDPZNww/jNOEgAZZk5RUEkTT1eBI4RE/HUx
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIH1zW+/pFqHAygL4ypiB5CZjqq+aucQzsom+JnAQdXQaoAoGCCqGSM49 AwEHoUQDQgAEE1Ojs+8dpwjEkIBIAU5AfVmQziK8TrM+mlrLJahWA+um3NghNmak 5E9ayhPrdn+vp9zd3DNBH4KjC1Q90dJLqA==
-----END EC PRIVATE KEY-----
RCAC with Corresponding Private Key in an X.509 PEM Format
RCAC Printed in an X.509 DER Format
Certificate: Data:
Version: 3 (0x2)
Serial Number: 6479173750095827996 (0x59eaa632947f541c) Signature Algorithm: ecdsa-with-SHA256
Issuer: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001
Validity
Not Before: Oct 15 14:23:43 2020 GMT
Not After : Oct 15 14:23:42 2040 GMT
Subject: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:13:53:a3:b3:ef:1d:a7:08:c4:90:80:48:01:4e:
40:7d:59:90:ce:22:bc:4e:b3:3e:9a:5a:cb:25:a8:
56:03:eb:a6:dc:d8:21:36:66:a4:e4:4f:5a:ca:13:
eb:76:7f:af:a7:dc:dd:dc:33:41:1f:82:a3:0b:54: 3d:d1:d2:4b:a8
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:TRUE
X509v3 Key Usage: critical Certificate Sign, CRL Sign
X509v3 Subject Key Identifier: 13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D
X509v3 Authority Key Identifier: keyid:13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D
Signature Algorithm: ecdsa-with-SHA256 30:45:02:20:45:81:64:46:6c:8f:19:5a:bc:0a:bb:7c:6c:b5:
a2:7a:83:f4:1d:37:f8:d5:3b:ee:c5:20:ab:d2:a0:da:05:09:
02:21:00:b8:a7:c2:5c:04:2e:30:cf:64:dc:30:fe:33:4e:12:
00:19:66:4e:51:50:49:13:4f:57:81:23:84:44:fc:75:31
RCAC in Matter TLV Format
15 | 30 | 01 | 08 | 59 | ea | a6 | 32 | 94 | 7f | 54 | 1c | 24 | 02 | 01 | 37 | 03 | 27 | 14 | 01 | 00 | 00 | 00 | ca |
ca | ca | ca | 18 | 26 | 04 | ef | 17 | 1b | 27 | 26 | 05 | 6e | b5 | b9 | 4c | 37 | 06 | 27 | 14 | 01 | 00 | 00 | 00 |
ca | ca | ca | ca | 18 | 24 | 07 | 01 | 24 | 08 | 01 | 30 | 09 | 41 | 04 | 13 | 53 | a3 | b3 | ef | 1d | a7 | 08 | c4 |
90 | 80 | 48 | 01 | 4e | 40 | 7d | 59 | 90 | ce | 22 | bc | 4e | b3 | 3e | 9a | 5a | cb | 25 | a8 | 56 | 03 | eb | a6 |
dc | d8 | 21 | 36 | 66 | a4 | e4 | 4f | 5a | ca | 13 | eb | 76 | 7f | af | a7 | dc | dd | dc | 33 | 41 | 1f | 82 | a3 |
0b | 54 | 3d | d1 | d2 | 4b | a8 | 37 | 0a | 35 | 01 | 29 | 01 | 18 | 24 | 02 | 60 | 30 | 04 | 14 | 13 | af | 81 | ab |
37 | 37 | 4b | 2e | d2 | a9 | 64 | 9b | 12 | b7 | a3 | a4 | 28 | 7e | 15 | 1d | 30 | 05 | 14 | 13 | af | 81 | ab | 37 |
37 | 4b | 2e | d2 | a9 | 64 | 9b | 12 | b7 | a3 | a4 | 28 | 7e | 15 | 1d | 18 | 30 | 0b | 40 | 45 | 81 | 64 | 46 | 6c |
8f | 19 | 5a | bc | 0a | bb | 7c | 6c | b5 | a2 | 7a | 83 | f4 | 1d | 37 | f8 | d5 | 3b | ee | c5 | 20 | ab | d2 | a0 |
da | 05 | 09 | b8 | a7 | c2 | 5c | 04 | 2e | 30 | cf | 64 | dc | 30 | fe | 33 | 4e | 12 | 00 | 19 | 66 | 4e | 51 | 50 |
49 | 13 | 4f | 57 | 81 | 23 | 84 | 44 | fc | 75 | 31 | 18 |
}
]],
signature = 45 81 64 46 6C 8F 19 5A BC 0A BB 7C 6C B5 A2 7A
83 F4 1D 37 F8 D5 3B EE C5 20 AB D2 A0 DA 05 09
B8 A7 C2 5C 04 2E 30 CF 64 DC 30 FE 33 4E 12 00
19 66 4E 51 50 49 13 4F 57 81 23 84 44 FC 75 31
= 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4
28 7E 15 1D,
= 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4
28 7E 15 1D,
authority-key-id
matter-certificate = {
serial-num = 59 EA A6 32 94 7F 54 1C,
sig-algo = 0x01U,
issuer = [[ matter-rcac-id = 0xCACACACA00000001U ]],
not-before = 0x271B17EFU,
not-after = 0x4CB9B56EU,
subject = [[ matter-rcac-id = 0xCACACACA00000001U ]], pub-key-algo = 0x01U,
ec-curve-id = 0x01U,
ec-pub-key = 04 13 53 A3 B3 EF 1D A7 08 C4 90 80 48 01 4E 40
7D 59 90 CE 22 BC 4E B3 3E 9A 5A CB 25 A8 56 03
EB A6 DC D8 21 36 66 A4 E4 4F 5A CA 13 EB 76 7F AF A7 DC DD DC 33 41 1F 82 A3 0B 54 3D D1 D2 4B A8,
extensions = [[ basic-constraints = {
is-ca = true
},
key-usage = 0x60U, subject-key-id
RCAC Printed in Matter TLV Schema Format
The same ICAC in X.509 and Matter TLV formats is presented in this section. An issuer of this ICAC is RCAC from previous section.
-----BEGIN CERTIFICATE-----
MIIBnTCCAUOgAwIBAgIILbREhVZBrt8wCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB gqJ8AQQMEENBQ0FDQUNBMDAwMDAwMDEwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 MTQyMzQyWjAiMSAwHgYKKwYBBAGConwBAwwQQ0FDQUNBQ0EwMDAwMDAwMzBZMBMG
ByqGSM49AgEGCCqGSM49AwEHA0IABMXQhhu4+QxAXBIxTkxevuqTn3J3S8wzI54v Wfb0avjcfUaCoOPMxkbm3ynqhr9WKucgqJgzfTg/MsCgnkFgGeqjYzBhMA8GA1Ud EwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRTUtcFnpwVpQiQ
aGKGSAGinx9B0zAfBgNVHSMEGDAWgBQTr4GrNzdLLtKpZJsSt6OkKH4VHTAKBggq hkjOPQQDAgNIADBFAiEAhBoG1Dten+zSToexJE61HGos8g2bXmugfxHmAC9+DKMC IE4ypgLDYJ0AktNIvb0ZihFGRr1BzxA3g2Qa4l4/I/0m
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIBGEO9zwrSBtsQJRpU2sWB11+ZL8tSJ1KiFs15xxdUapoAoGCCqGSM49
AwEHoUQDQgAExdCGG7j5DEBcEjFOTF6+6pOfcndLzDMjni9Z9vRq+Nx9RoKg48zG RubfKeqGv1Yq5yComDN9OD8ywKCeQWAZ6g==
-----END EC PRIVATE KEY-----
ICAC with Corresponding Private Key in an X.509 PEM Format
ICAC Printed in an X.509 DER Format
Certificate: Data:
Version: 3 (0x2)
Serial Number: 3293332566983159519 (0x2db444855641aedf) Signature Algorithm: ecdsa-with-SHA256
Issuer: 1.3.6.1.4.1.37244.1.4 = CACACACA00000001
Validity
Not Before: Oct 15 14:23:43 2020 GMT
Not After : Oct 15 14:23:42 2040 GMT
Subject: 1.3.6.1.4.1.37244.1.3 = CACACACA00000003
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:c5:d0:86:1b:b8:f9:0c:40:5c:12:31:4e:4c:5e:
be:ea:93:9f:72:77:4b:cc:33:23:9e:2f:59:f6:f4:
6a:f8:dc:7d:46:82:a0:e3:cc:c6:46:e6:df:29:ea:
86:bf:56:2a:e7:20:a8:98:33:7d:38:3f:32:c0:a0:
9e:41:60:19:ea
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:TRUE
X509v3 Key Usage: critical Certificate Sign, CRL Sign
X509v3 Subject Key Identifier: 53:52:D7:05:9E:9C:15:A5:08:90:68:62:86:48:01:A2:9F:1F:41:D3
X509v3 Authority Key Identifier: keyid:13:AF:81:AB:37:37:4B:2E:D2:A9:64:9B:12:B7:A3:A4:28:7E:15:1D
Signature Algorithm: ecdsa-with-SHA256 30:45:02:21:00:84:1a:06:d4:3b:5e:9f:ec:d2:4e:87:b1:24:
4e:b5:1c:6a:2c:f2:0d:9b:5e:6b:a0:7f:11:e6:00:2f:7e:0c:
a3:02:20:4e:32:a6:02:c3:60:9d:00:92:d3:48:bd:bd:19:8a:
11:46:46:bd:41:cf:10:37:83:64:1a:e2:5e:3f:23:fd:26
ICAC in Matter TLV Format
15 | 30 | 01 | 08 | 2d | b4 | 44 | 85 | 56 | 41 | ae | df | 24 | 02 | 01 | 37 | 03 | 27 | 14 | 01 | 00 | 00 | 00 | ca |
ca | ca | ca | 18 | 26 | 04 | ef | 17 | 1b | 27 | 26 | 05 | 6e | b5 | b9 | 4c | 37 | 06 | 27 | 13 | 03 | 00 | 00 | 00 |
ca | ca | ca | ca | 18 | 24 | 07 | 01 | 24 | 08 | 01 | 30 | 09 | 41 | 04 | c5 | d0 | 86 | 1b | b8 | f9 | 0c | 40 | 5c |
12 | 31 | 4e | 4c | 5e | be | ea | 93 | 9f | 72 | 77 | 4b | cc | 33 | 23 | 9e | 2f | 59 | f6 | f4 | 6a | f8 | dc | 7d |
46 | 82 | a0 | e3 | cc | c6 | 46 | e6 | df | 29 | ea | 86 | bf | 56 | 2a | e7 | 20 | a8 | 98 | 33 | 7d | 38 | 3f | 32 |
c0 | a0 | 9e | 41 | 60 | 19 | ea | 37 | 0a | 35 | 01 | 29 | 01 | 18 | 24 | 02 | 60 | 30 | 04 | 14 | 53 | 52 | d7 | 05 |
9e | 9c | 15 | a5 | 08 | 90 | 68 | 62 | 86 | 48 | 01 | a2 | 9f | 1f | 41 | d3 | 30 | 05 | 14 | 13 | af | 81 | ab | 37 |
37 | 4b | 2e | d2 | a9 | 64 | 9b | 12 | b7 | a3 | a4 | 28 | 7e | 15 | 1d | 18 | 30 | 0b | 40 | 84 | 1a | 06 | d4 | 3b |
5e | 9f | ec | d2 | 4e | 87 | b1 | 24 | 4e | b5 | 1c | 6a | 2c | f2 | 0d | 9b | 5e | 6b | a0 | 7f | 11 | e6 | 00 | 2f |
7e | 0c | a3 | 4e | 32 | a6 | 02 | c3 | 60 | 9d | 00 | 92 | d3 | 48 | bd | bd | 19 | 8a | 11 | 46 | 46 | bd | 41 | cf |
10 | 37 | 83 | 64 | 1a | e2 | 5e | 3f | 23 | fd | 26 | 18 |
}
]],
signature = 84 1A 06 D4 3B 5E 9F EC D2 4E 87 B1 24 4E B5 1C
6A 2C F2 0D 9B 5E 6B A0 7F 11 E6 00 2F 7E 0C A3
4E 32 A6 02 C3 60 9D 00 92 D3 48 BD BD 19 8A 11
46 46 BD 41 CF 10 37 83 64 1A E2 5E 3F 23 FD 26
= 53 52 D7 05 9E 9C 15 A5 08 90 68 62 86 48 01 A2 9F 1F 41 D3,
= 13 AF 81 AB 37 37 4B 2E D2 A9 64 9B 12 B7 A3 A4
28 7E 15 1D,
authority-key-id
matter-certificate = {
serial-num = 2D B4 44 85 56 41 AE DF,
sig-algo = 0x01U,
issuer = [[ matter-rcac-id = 0xCACACACA00000001U ]],
not-before = 0x271B17EFU,
not-after = 0x4CB9B56EU,
subject = [[ matter-icac-id = 0xCACACACA00000003U ]], pub-key-algo = 0x01U,
ec-curve-id = 0x01U,
ec-pub-key = 04 C5 D0 86 1B B8 F9 0C 40 5C 12 31 4E 4C 5E BE
EA 93 9F 72 77 4B CC 33 23 9E 2F 59 F6 F4 6A F8
DC 7D 46 82 A0 E3 CC C6 46 E6 DF 29 EA 86 BF 56
2A E7 20 A8 98 33 7D 38 3F 32 C0 A0 9E 41 60 19 EA,
extensions = [[ basic-constraints = {
is-ca = true
},
key-usage = 0x60U, subject-key-id
ICAC Printed in Matter TLV Schema Format
The same NOC in X.509 and Matter TLV formats is presented in this section. An issuer of this NOC is ICAC from previous section.
NOC with Corresponding Private Key in an X.509 PEM Format
-----BEGIN CERTIFICATE-----
MIIB4DCCAYagAwIBAgIIPvz/FwK5oXowCgYIKoZIzj0EAwIwIjEgMB4GCisGAQQB gqJ8AQMMEENBQ0FDQUNBMDAwMDAwMDMwHhcNMjAxMDE1MTQyMzQzWhcNNDAxMDE1 MTQyMzQyWjBEMSAwHgYKKwYBBAGConwBAQwQREVERURFREUwMDAxMDAwMTEgMB4G
CisGAQQBgqJ8AQUMEEZBQjAwMDAwMDAwMDAwMUQwWTATBgcqhkjOPQIBBggqhkjO PQMBBwNCAASaKiFvs53WtvohG4NciePmr7ZsFPdYMZVPn/T3o/ARLIoNjq8pxlMp TUju4HCKAyzKOTk8OntG8YGuoHj+rYODo4GDMIGAMAwGA1UdEwEB/wQCMAAwDgYD VR0PAQH/BAQDAgeAMCAGA1UdJQEB/wQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAd BgNVHQ4EFgQUn1Wia35DA+YIg+kTv5T0+14qYWEwHwYDVR0jBBgwFoAUU1LXBZ6c
FaUIkGhihkgBop8fQdMwCgYIKoZIzj0EAwIDSAAwRQIgeVXCAmMLS6TVkSUmMi/f KPie3+WvnA5XK9ihSqq7TRICIQC4PKF8ewX7Fkt315xSlhMxa8/ReJXksqTyQEuY FzJxWQ==
-----END CERTIFICATE-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIKVls/ooqO1qdPtvD/ik00DZ4a6Y8h36HwpZpOoCGhYnoAoGCCqGSM49 AwEHoUQDQgAEmiohb7Od1rb6IRuDXInj5q+2bBT3WDGVT5/096PwESyKDY6vKcZT KU1I7uBwigMsyjk5PDp7RvGBrqB4/q2Dgw==
-----END EC PRIVATE KEY-----
NOC Printed in an X.509 DER Format
Certificate: Data:
Version: 3 (0x2)
Serial Number: 4538782998777667962 (0x3efcff1702b9a17a) Signature Algorithm: ecdsa-with-SHA256
Issuer: 1.3.6.1.4.1.37244.1.3 = CACACACA00000003
Validity
Not Before: Oct 15 14:23:43 2020 GMT
Not After : Oct 15 14:23:42 2040 GMT
Subject: 1.3.6.1.4.1.37244.1.1 = DEDEDEDE00010001, 1.3.6.1.4.1.37244.1.5 = FAB000000000001D
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit)
pub:
04:9a:2a:21:6f:b3:9d:d6:b6:fa:21:1b:83:5c:89:
e3:e6:af:b6:6c:14:f7:58:31:95:4f:9f:f4:f7:a3:
f0:11:2c:8a:0d:8e:af:29:c6:53:29:4d:48:ee:e0:
70:8a:03:2c:ca:39:39:3c:3a:7b:46:f1:81:ae:a0:
78:fe:ad:83:83
ASN1 OID: prime256v1 NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical CA:FALSE
X509v3 Key Usage: critical Digital Signature
X509v3 Extended Key Usage: critical
TLS Web Client Authentication, TLS Web Server Authentication X509v3 Subject Key Identifier:
9F:55:A2:6B:7E:43:03:E6:08:83:E9:13:BF:94:F4:FB:5E:2A:61:61
X509v3 Authority Key Identifier: keyid:53:52:D7:05:9E:9C:15:A5:08:90:68:62:86:48:01:A2:9F:1F:41:D3
Signature Algorithm: ecdsa-with-SHA256 30:45:02:20:79:55:c2:02:63:0b:4b:a4:d5:91:25:26:32:2f:
df:28:f8:9e:df:e5:af:9c:0e:57:2b:d8:a1:4a:aa:bb:4d:12:
02:21:00:b8:3c:a1:7c:7b:05:fb:16:4b:77:d7:9c:52:96:13:
31:6b:cf:d1:78:95:e4:b2:a4:f2:40:4b:98:17:32:71:59
NOC in Matter TLV Format
15 | 30 | 01 | 08 | 3e | fc | ff | 17 | 02 | b9 | a1 | 7a | 24 | 02 | 01 | 37 | 03 | 27 | 13 | 03 | 00 | 00 | 00 | ca |
ca | ca | ca | 18 | 26 | 04 | ef | 17 | 1b | 27 | 26 | 05 | 6e | b5 | b9 | 4c | 37 | 06 | 27 | 11 | 01 | 00 | 01 | 00 |
de | de | de | de | 27 | 15 | 1d | 00 | 00 | 00 | 00 | 00 | b0 | fa | 18 | 24 | 07 | 01 | 24 | 08 | 01 | 30 | 09 | 41 |
04 | 9a | 2a | 21 | 6f | b3 | 9d | d6 | b6 | fa | 21 | 1b | 83 | 5c | 89 | e3 | e6 | af | b6 | 6c | 14 | f7 | 58 | 31 |
95 | 4f | 9f | f4 | f7 | a3 | f0 | 11 | 2c | 8a | 0d | 8e | af | 29 | c6 | 53 | 29 | 4d | 48 | ee | e0 | 70 | 8a | 03 |
2c | ca | 39 | 39 | 3c | 3a | 7b | 46 | f1 | 81 | ae | a0 | 78 | fe | ad | 83 | 83 | 37 | 0a | 35 | 01 | 28 | 01 | 18 |
24 | 02 | 01 | 36 | 03 | 04 | 02 | 04 | 01 | 18 | 30 | 04 | 14 | 9f | 55 | a2 | 6b | 7e | 43 | 03 | e6 | 08 | 83 | e9 |
13 | bf | 94 | f4 | fb | 5e | 2a | 61 | 61 | 30 | 05 | 14 | 53 | 52 | d7 | 05 | 9e | 9c | 15 | a5 | 08 | 90 | 68 | 62 |
86 | 48 | 01 | a2 | 9f | 1f | 41 | d3 | 18 | 30 | 0b | 40 | 79 | 55 | c2 | 02 | 63 | 0b | 4b | a4 | d5 | 91 | 25 | 26 |
32 | 2f | df | 28 | f8 | 9e | df | e5 | af | 9c | 0e | 57 | 2b | d8 | a1 | 4a | aa | bb | 4d | 12 | b8 | 3c | a1 | 7c |
7b | 05 | fb | 16 | 4b | 77 | d7 | 9c | 52 | 96 | 13 | 31 | 6b | cf | d1 | 78 | 95 | e4 | b2 | a4 | f2 | 40 | 4b | 98 |
17 | 32 | 71 | 59 | 18 |
matter-certificate = {
serial-num = 3E FC FF 17 02 B9 A1 7A,
sig-algo = 0x01U,
issuer = [[ matter-icac-id = 0xCACACACA00000003U ]],
not-before = 0x271B17EFU,
not-after = 0x4CB9B56EU,
subject = [[ matter-node-id = 0xDEDEDEDE00010001U,
matter-fabric-id = 0xFAB000000000001DU ]],
pub-key-algo = 0x01U,
ec-curve-id = 0x01U,
ec-pub-key = 04 9A 2A 21 6F B3 9D D6 B6 FA 21 1B 83 5C 89 E3
E6 AF B6 6C 14 F7 58 31 95 4F 9F F4 F7 A3 F0 11
2C 8A 0D 8E AF 29 C6 53 29 4D 48 EE E0 70 8A 03
2C CA 39 39 3C 3A 7B 46 F1 81 AE A0 78 FE AD 83
83,
extensions = [[ basic-constraints = {
is-ca = false
},
key-usage = 0x01U,
extended-key-usage = [ 0x02U, 0x01U ],
subject-key-id = 9F 55 A2 6B 7E 43 03 E6 08 83 E9 13 BF 94 F4 FB
5E 2A 61 61,
authority-key-id = 53 52 D7 05 9E 9C 15 A5 08 90 68 62 86 48 01 A2
9F 1F 41 D3,
]],
signature = 79 55 C2 02 63 0B 4B A4 D5 91 25 26 32 2F DF 28
F8 9E DF E5 AF 9C 0E 57 2B D8 A1 4A AA BB 4D 12 B8 3C A1 7C 7B 05 FB 16 4B 77 D7 9C 52 96 13 31
6B CF D1 78 95 E4 B2 A4 F2 40 4B 98 17 32 71 59
}
NOC Printed in Matter TLV Schema Format
This section specifies the features related to controlling access to a Node’s Endpoint Clusters ("Targets" hereafter) from other Nodes. The overall features are collectively named "Access Control" hereafter.
The Access Control features aim to ensure that only authorized Nodes are permitted access to given application-layer functionality exposed by the Data Model, through the Interaction Model. Access Control is the fundamental link between the Secure Channel and the Interaction Model.
In order to implement a policy of Access Control, Administrators on the fabric create and maintain a consistent distributed configuration of Access Control Lists (ACLs) across all Nodes. Each Node has an ACL containing Access Control Entries which codify the policy. The Access Control Cluster exposes a data model view of a Node’s ACL which enables its maintenance.
The Access Control system is rule-based with no implicit access permitted by default. Access to a Node’s Targets is denied unless the Access Control system grants the required privilege level to a given Subject to interact with given Targets on that Node. Initial Access Control privileges are bootstrapped during the commissioning phase, and maintained thereafter by Administrators.
All access privileges, from the AccessControlEntryPrivilegeEnum enumeration, SHALL be granted by Access Control. Thus, the Initiator ("Subject" hereafter) of any Interaction Model action SHALL NOT succeed in executing a given action on a Node’s Target unless that Node’s Access Control system explicitly grants the required privilege to that Subject for that particular action.
The Access Control system grants privileges by checking and verifying all attempted access against rules explicitly codified in Access Control Entries within the Node’s Access Control List. Additionally, Access Control implicitly grants administrative access privileges to an Administrative Subject during a Node’s commissioning phase.
Access Control Entries contain:
A FabricIndex scoping the entry to the Associated Fabric.
A Privilege level granted by the entry (see AccessControlEntryPrivilegeEnum)
View: reading or subscribing to data from a non-Proxy
Proxy View: reading or subscribing to data from a Proxy
Operate: writing operational data and invoking operational commands
Manage: writing configuration data and invoking configuration commands (for example,
Binding and Group Clusters access)
Administer: writing administrative data and invoking administrative commands (for example, Access Control and Commissioning Clusters access)
A list of target Clusters to which the entry applies
A list of source Subjects to which the entry applies
An Authentication Mode that describes the type of secure channel authentication method to which the entry’s subjects apply
The meaning of a "Subject" is primarily that of describing the source for an action, using a given authentication method provided by the Secure Channel architecture. A subject SHALL be one of:
A passcode, identified by a Passcode ID, authenticated locally by a PASE session, during the commissioning phase.
Note that any Passcode ID other than 0, which is the default commissioning passcode, is reserved for future use.
Furthermore, ACL entries with a PASE authentication mode SHALL NOT be explicitly added to the Access Control List, since there is an invisible implicit administrative entry (see Section 6.6.2.8, “Bootstrapping of the Access Control Cluster”) always equivalently present on the Commissionee (but not the Commissioner) during PASE sessions.
A source node, authenticated by a CASE session using its Operational Certificate, during the operational phase. The source node can be identified by its Node ID and/or by CASE Authenticated Tags.
A destination group, identified by a destination Group ID in the message, authenticated by an Operational Group Key from the Group Key Management Cluster, during the operational phase.
PASE and Group Subjects
Note that the subject is not considered to be an individual Node when the authentication is via passcode or group symmetric key; in these cases, the administrative root of trust is conditional only upon bearing the correct passcode during session establishment, or bearing the Operational Group Key when constructing a group message.
Subjects identified by CASE Authenticated Tag
In contrast, a CASE Authenticated Tag (CAT) is a special subject distinguished name within the Operational Certificate shared during CASE session establishment that functions as a group-like tag. Such a tag can be applied to several Nodes, thereby facilitating management of Access Control Entries that use the same set of Nodes as subjects. Because these tags are authenticated within the CASE session context, the administrative root of trust does chain back through the individual source Node to the Fabric’s trusted root. This makes CATs suitable for group-like use while maintaining secure authentication and attribution ability.
Each CAT is 32-bit and equally divided into identifier value and its corresponding version:
The upper 16-bits are allocated to identifier value
The lower 16-bits are allocated to the version number
The version number represents current version of specific identifier value. An Administrator MAY increment the version number on any changes in the set of Nodes sharing the given tag. Version number is a monotonically increasing natural number in the range of 1 to 65535. A version number
of 0 is invalid and SHALL NOT be used. On reaching the maximum value (65535), wrap-around is not supported and the tag identifier SHOULD be retired by an Administrator since version increase will no longer be possible.
When a CAT appears in the Subjects list of an Access Control Entry, it SHALL be encoded within the CASE Authenticated Tag sub-space of Node Identifiers, with the upper 32 bits set to 0xFFFF_FFFD. Note that this encoding cannot appear as an operational Node ID. It is merely a sub-encoding allowing the 64-bit scalars in an Access Control Entry’s Subjects list to represent both Node IDs and CATs.
Example CASE Authenticated Tags:
Tag identifier 0xAB12, Version 0x0003
CAT value: 0xAB12_0003
Appears in Access Control Entry Subjects list as 0xFFFF_FFFD_AB12_0003
Appears in Node Operational Certificate subject under OID 1.3.6.1.4.1.37244.1.6 with value 0xAB120003
Would appear in X.509 certificate subject under OID 1.3.6.1.4.1.37244.1.6 as UTF8String
AB120003 for signature validation purposes.
Tag identifier 0x071C, Version 0x1074
CAT value: 0x071C_1074
Appears in Access Control Entry Subjects list as 0xFFFF_FFFD_071C_1074
Appears in Node Operational Certificate subject under OID 1.3.6.1.4.1.37244.1.6 with value 0x071C1074
Would appear in X.509 certificate subject under OID 1.3.6.1.4.1.37244.1.6 as UTF8String
071C1074 for signature validation purposes.
The Subjects list of an Access Control Entry MAY grant a given privilege to more than one Subject, if the Authentication Mode allows it, such as in the case of the CASE and Group Authentication Modes. An empty Subjects list SHALL mean that every possible Subject employing the stated Authentication Mode is granted the entry’s privilege over the Targets.
The Targets list of an Access Control Entry MAY grant a given privilege to more than one Target. An empty Targets list SHALL mean that every Cluster on every Endpoint exposed by the Node is accessible using the granted privilege to any matching Subject. Each Target in the Targets list SHALL specify Cluster instances directly by Cluster ID (on any Endpoint, or limited to particular Endpoints), indirectly by Endpoint ID (all Cluster instances on that Endpoint), or indirectly by Device Type ID (all Cluster instances on all Endpoints containing that Device Type).
For both the Subjects list and Targets list of an Access Control Entry, empty lists permit a rudimentary form of "wildcard" behavior, which is especially useful for codifying policies providing common view/read/discover access to a given subset of Nodes based on Authentication Mode.
Given that "wildcard" (that is, any subject/target) granting is possible with an empty Subjects list or an empty Targets list, it follows that care must be taken by Administrators generating and distributing Access Control Lists to ensure unintended access does not arise. It is RECOMMENDED to avoid updating Access Control Entries in such a way as to remove Subjects or Targets one by one, which may result in a wildcard after individual actions. Rather, entire Targets/Subjects lists SHOULD be written atomically in a single action, to ensure a complete final state is achieved, with either wildcard or not, and that no accidental wildcards arise. Furthermore, such ACL entries with wildcard subject should be deployed with care as they grant the named privilege level to potentially many senders, especially when Group Authentication Mode is specified.
The Subjects for an Access Control Entry are logical subjects, configured through policy by an Administrator, including possibly a Commissioner during the commissioning phase. A given implementation of administrative logic MAY assign authentication identities to Nodes directly associated with physical end-users (for example, a mobile device of a given end-user). However, since Nodes are logical networking entities, the specific policy of how Node identities are mapped to physical end-users and physical devices is implementation-specific. Therefore, the access granted by a given Node’s Access Control system should not be construed as having any particular meaning in regards to physical end-users other than the fact that a given set of Administrators computed a consistent set of Access Control Lists to effect a desired system functionality across all Nodes they administer and end-users they represent.
Since the target of a given Access Control Entry is a list of Targets, and since Targets (that is, Clusters on Endpoints) are Interaction Model constructs, it should be assumed that access control functionality as described within this model is constrained to the interaction model layer. However, constraints on incoming session establishment requests MAY be affected by the Access Control system, based on implementation-defined rules. For example, a Node MAY deny CASE session establishment from an initiator whose identity doesn’t match any Access Control Entry. These types of rules are implementation-specific and SHOULD be carefully considered, if applied at all. For example, due to the richness of Access Control Entry encoding for Subjects, significant care has to be taken to avoid incorrectly rejecting an incoming CASE session establishment that could be valid. Rejecting valid connections could cause a Node to become unreachable. Any constraints on transport-level and network-level functionality, including but not limited to the availability of commissioning-mode connectivity, are out of Access Control scope.
The Message Layer SHALL provide sufficient metadata (e.g. Authentication Mode, source identity) about incoming messages to the Interaction Model protocol layer in order to properly enforce Access Control.
An Incoming Subject Descriptor (ISD) is a mapping from the security layer fields of an incoming
Message to a tuple of <AuthMode, SubjectDescriptor> that can map unambiguously to an Access Control Entry’s Subjects and AuthMode fields. See Section 6.6.5.1.2, “Incoming Subject Descriptor (ISD) Structure” for further details.
An implementation MAY use Access Control Extensions to extend the base Access Control model. Since all extensions are installed by Administrators for a fabric, it is expected that only extensions that would improve overall security will be applied. Since every Vendor MAY implement extensions as they see fit, it SHOULD NOT be expected that an extension will be supported by every Node. It is therefore RECOMMENDED that careful consideration of interoperability concerns be given when implementing Access Control Extensions. A fabric’s Administrators MAY always read a given Node’s Access Control Entries and Access Control Extensions pertaining to the fabric. Therefore, Administrators MAY use extensions to record auditing metadata about Access Control Entries which are not for operational use by the Node.
A Node SHALL preserve every field of the installed Access Control Cluster, including extensions when present, without internally-initiated modifications, so that they may be read-back verbatim upon receiving an appropriate request from an Administrator.
The Access Control Cluster SHALL NOT be used to encode application-level permissions and configurations such as smart lock PIN codes or similar user-facing security functionality. Application-level security is best served by finer-grained capabilities described and addressed by application-domain-specific clusters.
Updates to the Access Control List through Access Control Cluster attributes and commands SHALL be restricted by the same Access Control mechanisms as all other clusters on the Node, and therefore require a grant of Administer privilege. Administrators are able to bootstrap a Node’s Access Control List during the commissioning phase due to the Access Control Privilege Granting algorithm implicitly granting the Administer privilege to Administrative Subject Nodes over a PASE commissioning channel; this implicit privilege grant applies for the Commissioner to administer the Commissionee, but not in the opposite direction.
The recording of a given Interaction Model Action’s attribution to a source entity is distinct from the contents of an Access Control Entry. Action Attribution SHALL be recorded against the Incoming Subject Descriptor (see Section 6.6.5.1.2, “Incoming Subject Descriptor (ISD) Structure”) rather than against any matched Access Control Entry’s contents.
Since the Administer privilege level grants wide access to a Node for a given Subject, it SHALL NOT be valid to have an Administer privilege set on an Access Control Entry, unless the AuthMode's AuthModeCategory is "CASE". For example, an AuthModeCategory of "Group", which admits no source Node authentication and reduced attribution ability, SHALL NOT be used to grant Administer
privilege.
The following Access Control Lists illustrate the flexibility of codifying access control policy using concrete examples.
Access Control Cluster: { ACL: [], // empty
Extension: [] // empty (omitted hereafter)
}
Upon Factory Data Reset, the Access Control Cluster is empty, having an Access Control List with no entries.
// entire node
// implicit entry only; does not explicitly exist!
// not fabric-specific
Access Control Cluster: { ACL: [
0: {
FabricIndex: 0, Privilege: Administer, AuthMode: PASE, Subjects: [],
Targets: []
}
]
}
However, the Access Control Privilege Granting algorithm behaves as if, over a PASE commissioning channel during the commissioning phase, the following implicit Access Control Entry were present on the Commissionee (but not the Commissioner) to grant Administer privilege for the entire Node.
During the commissioning phase, the AddNOC command automatically creates an Access Control Entry granting Administer privilege for the entire Node, the appropriate CASE authenticated Subject (in this case, Node ID 0xAAAA_AAAA_AAAA_AAAA) on the appropriate Fabric (in this case, Fabric 0xFAB0_0000_0000_001D as Fabric index 1).
Access Control Cluster: { ACL: [
0: {
FabricIndex: 1, Privilege: Administer, AuthMode: CASE,
Subjects: [ 0xAAAA_AAAA_AAAA_AAAA ], Targets: []
}
]
}
Access Control Cluster: { ACL: [
... 1: {
FabricIndex: 1, Privilege: View, AuthMode: CASE, Subjects: [], Targets: []
}
]
}
An Administrator adds an Access Control Entry which grants View privilege, for the entire Node, to all CASE authenticated Nodes.
Access Control Cluster: { ACL: [
... 2: {
FabricIndex: 1, Privilege: Manage, AuthMode: Group,
Subjects: [ 0x0000_0000_0000_0001 ],
Targets: [ { Endpoint: 1 }, { Endpoint: 3 } ]
}
]
}
An Administrator adds an Access Control Entry which grants Manage privilege, for endpoints 1 and 3, to any Nodes which can authenticate as members of Group 1.
An Administrator revises this Access Control Entry to grant the same privilege, for only the pump configuration and control cluster (0x0202) on endpoint 3, and for any door lock cluster (0x0101) on the entire Node, to the same Nodes.
Access Control Cluster: { ACL: [
... 2: {
FabricIndex: 1, Privilege: Manage, AuthMode: Group,
Subjects: [ 0x0000_0000_0000_0001 ],
Targets: [ { Endpoint: 1 }, { Endpoint: 3, Cluster: 0x0000_0202 }, { Cluster: 0x0000_0101 } ]
}
]
}
Access Control Cluster: { ACL: [
... 3: {
FabricIndex: 1, Privilege: Operate, AuthMode: CASE,
Subjects: [ 0x1111_1111_1111_1111, 0x2222_2222_2222_2222 ],
Targets: [ { DeviceType: 0x0000_010D } ]
}
]
}
An Administrator adds an Access Control Entry which grants Operate privilege, for all endpoints containing the extended color light device (0x010D) on the entire Node, to CASE authenticated Nodes 0x1111_1111_1111_1111 and 0x2222_2222_2222_2222.
A Commissioner adds four more Nodes into an existing fabric. These new Nodes have Node IDs 0x3333_3333_3333_3333, 0x4444_4444_4444_4444, 0x5555_5555_5555_5555 and
0x6666_6666_6666_6666 respectively. The Fabric Administration policy requires associating these four nodes and an existing node (0x2222_2222_2222_2222) into a CAT group.
To achieve this, an Administrator will issue NOCs to all five nodes in this CAT group with a CAT value of 0xABCD_0001, which is tag identifier value 0xABCD and version 1, and encoded as subject value 0xFFFF_FFFD_ABCD_0001. To distribute these CATs, an Administrator obtains NOCs from its certificate authority with the requisite subjects including the desired CAT. They are either initially provisioned with the AddNOC command during initial commissioning (for the new Nodes) or updated with UpdateNOC (for existing Nodes).
Then the Administrator grants permissions to the five nodes by updating the ACL of all relevant targets by adding an entry with subject of CAT (0xFFFF_FFFD_ABCD_0001). The Administrator may also remove entries where Node 0x2222_2222_2222_2222 appears as an explicit Subject if presentation of the CAT identifier value 0xABCD and version value 0x0001 confers an equivalent privilege. Note that any Node with CAT identifier value of 0xABCD and version value 0x0001 or
Access Control Cluster: { ACL: [
... 3: {
FabricIndex: 1, Privilege: Operate, AuthMode: CASE,
Subjects: [ 0x1111_1111_1111_1111, 0xFFFF_FFFD_ABCD_0001],
Targets: [ { DeviceType: 0x0000_010D } ]
}
]
}
higher in their NOC will have this privilege.
An Administrator wants to remove the Node with Node ID 0x3333_3333_3333_3333 from the CAT group defined by CAT identifier value of 0xABCD, as installed in the previous example.
The Administrator could follow the steps outlined below:
Administrator will ensure that the removed node having Node ID 0x3333_3333_3333_3333 will not receive a new NOC with an CAT identifier value of 0xABCD. Note that the node removed from the group will continue to hold existing NOC (with CAT identifier of 0xABCD and version 0x0001).
An Administrator updates NOCs with CAT identifier value of 0xABCD and version 0x0002 (encoded as subject 0xFFFF_FFFD_ABCD_0002) in all remaining currently reachable Nodes within the CAT group to ensure they continue to have same privilege as before. In this example, Nodes having Node IDs 0x2222_2222_2222_2222, 0x4444_4444_4444_4444 and 0x5555_5555_5555_5555 are currently reachable.
Node with Node ID 0x6666_6666_6666_6666 from this CAT group is a valid member but was not reachable by an Administrator at the time of this change. This Node will continue to hold existing NOC with CAT of 0xABCD_0001.
After updating NOCs of all reachable Nodes, the Administrator SHOULD revise the Access Control Entry of all reachable nodes who have the previous CAT (encoded as subject 0xFFFF_FFFD_ABCD_0001) in an ACL entry, to remove privilege from the Node no longer in the grouping (i.e. those with version 0x0001) by increasing trusted version value to be higher than 0x0001. The Administrator decides to increment version value by one to set the new version value to be 0x0002.
Once ACL changes are propagated to all controlled nodes, they will no longer allow access privileges to any Node with older version (i.e. value less than 0x0002) of CAT identifier value 0xABCD. Hence, the node removed from the group, having Node ID 0x3333_3333_3333_3333 and CAT with identifier 0xABCD and version of 0x0001, can no longer access any of the controlled nodes whose ACL entries were updated to have a subject of 0xFFFF_FFFD_ABCD_0002 (CAT identifier value 0xABCD, version 0x0002).
Node having Node ID of 0x6666_6666_6666_6666 will not be able to access any Nodes by relying on CAT, since it does not have an NOC with latest CAT (with version 0x0002). However, it can still
access Nodes that list it as a subject Node ID explicitly. When an Administrator eventually establishes connection to this Node, the Administrator SHOULD update the NOC to the latest version, with CAT set to 0xABCD_0002. After having its NOC updated to have the newest version of the CAT, the Node with Node ID 0x6666_6666_6666_6666 will again have access to Nodes that list subject 0xFFFF_FFFD_ABCD_0002 (CAT identifier value 0xABCD, version 0x0002), with no further updates to ACL entries of existing Nodes.
Any controlled Node which previously held an ACL Entry with prior version of the updated CAT (subject 0xFFFF_FFFD_ABCD_0001) but was not reachable by an Administrator at the time of update, will continue to hold the previous Access Control Entry with a subject allowing CAT with identifier of 0xABCD and version 0x0001 or higher. Thus, these Nodes will grant privileges to any Node from the original CAT group (including Node ID 0x3333_3333_3333_3333). When an Administrator eventually establishes connection to this Node with older ACL entry, the Administrator SHOULD update it with the latest value, so that Node ID 0x3333_3333_3333_3333 no longer has privileges.
Note that in the above example, the CAT identifier value remained the same (0xABCD) in NOCs and ACL entries throughout these steps. Only the version portion was updated to effect changes to the meaning of the CAT.
As can be seen in the example above, there are multiple steps involving updates to NOCs and ACL entries to affect CAT-based grouping and aliasing policies. It is therefore possible that some Nodes may not receive these changes immediately, due to network reachability issues, such as being powered down for an extended period, and thus have ACL entries or NOCs that grant temporarily obsolete privileges. This is true as well with direct Node ID subjects, in general.
Access Control Cluster: { ACL: [
... 3: {
FabricIndex: 1, Privilege: Operate, AuthMode: CASE,
Subjects: [ 0x1111_1111_1111_1111, 0xFFFF_FFFD_ABCD_0002],
Targets: [ { DeviceType: 0x0000_010D } ]
}
]
}
Administrators SHOULD aim for best-effort eventual consistency while executing the steps outlined above.
Updates to the Access Control Cluster SHALL take immediate effect in the Access Control system. For example, given an Interaction Model action message containing the following actions, the Access Control Privilege Granting algorithm would grant a privilege of None for the second action, since the first action would take effect immediately beforehand.
Pre-conditions:
Access Control List has single entry: [{Privilege: Administer, Authmode: CASE (2), Subjects: [0x0011223344556677], Targets: []}]
Node ID 0x0011223344556677 over CASE is allowed Administer privilege for all targets
Incoming message Source is Node ID 0x0011223344556677 over CASE: matches Access Control Entry subject
Actions:
Action: Write (1st path)
Path: Endpoint[0]/Cluster[AccessControl]/Attribute[ACL]/ListIndex[0]/Field[Targets]
Value: [{Endpoint: 2}]
Single entry updated to target only Endpoint 2
Action: Write (2nd path)
Path: Endpoint[1]/Cluster[OnOff]/Attribute[OnTime]
Post-conditions:
Access Control List has single entry, updated by first path of Write Action: [{Privilege: Administer, Authmode: CASE (2), Subjects: [0x0011223344556677], Targets: [{Endpoint: 2}]}]
Node ID 0x0011223344556677 over CASE is allowed Administer privilege for only Endpoint 2 target
Note that in this example, the Node has inadvertently lost its ability to update the Access Control Cluster by limiting its Administer privilege to Endpoint 2.
This section describes an overall Conceptual Access Control Privilege Granting algorithm. Implementations of this algorithm SHALL have an identical outcome to the output of this conceptual algorithm described below.
The Interaction Model protocol, through its message handling, SHALL determine the privilege level granted per Target, on every instance where a Target is referenced for use.
Access Control List
The Access Control List contains several Access Control Entries, previously described in Section 6.6.2, “Model”.
The entry fields are:
Subjects List (SubjectID[] Subjects)
Targets List (TargetStruct[] Targets)
Authentication Mode value (AuthModeEnum AuthMode)
Privilege value (PrivilegeEnum Privilege)
Incoming Subject Descriptor (ISD) Structure
Each incoming message has a unique <AuthMode, SubjectDescriptor> applicable to it, whose derivation is deterministic based on both incoming message fields and session metadata fields. For example, if a message arrives that matches a given CASE Session ID, then the metadata for that CASE session would be used.
Computation of the ISD is described in Section 6.6.5.3, “Derivation of ISD from Incoming Message”. The ISD fields are as follows:
Commissioning Flag (bool IsCommissioning), whether the authentication is over a commissioning channel.
Authentication Mode (AuthModeEnum AuthMode), mapping to an authentication mode, directly comparable to Access Control Entry AuthMode.
Subjects List (list<SubjectID> Subjects), mapping incoming message source to a type of subject, such as a CASE session Source Node ID.
Fabric Index (FabricIndex FabricIndex), mapping to a fabric reference.
The algorithm takes as input:
the ISD of Incoming Message (subject_desc)
the Endpoint ID (endpoint_id) for which the querier requires a Privilege level
the Cluster ID (cluster_id) for which the querier requires a Privilege level
the Access Control List (acl) from the Access Control Cluster The output of the algorithm is:
A set of privileges granted for the Action Path, which is a subset of {View, ProxyView, Operate, Manage, Administer} as described in AccessControlEntryPrivilegeEnum.
The computation of the ISD is a pre-condition to the algorithm and is described in Section 6.6.5.3, “Derivation of ISD from Incoming Message”.
The goal is to find the complete set of privileges granted given the input. The principle of least privilege is respected by virtue of the entire Access Control List having been computed with rules such that the least privilege is granted to all subjects. Therefore, any Access Control Entry granting the required privilege to the subject for a given target is sufficient to determine whether access is allowed.
The algorithm SHALL function as follows:
def subject_matches(acl_subject, isd_subject):
# Subjects must match exactly, or both are CAT
# with matching CAT ID and acceptable CAT version return (acl_subject == isd_subject) or
(is_cat(acl_subject) and is_cat(isd_subject) and (get_cat_id(acl_subject) == get_cat_id(isd_subject)) and (get_cat_version(isd_subject) >= get_cat_version(acl_subject))
def add_granted_privilege(granted_privileges, privilege): # Add the new privilege to the granted privileges set granted_privileges.add(privilege)
# Also add any privileges subsumed by the new privilege if (privilege == PrivilegeEnum.ProxyView):
granted_privileges.add(PrivilegeEnum.View) elif (privilege == PrivilegeEnum.Operate):
granted_privileges.add(PrivilegeEnum.View) elif (privilege == PrivilegeEnum.Manage):
granted_privileges.add(PrivilegeEnum.Operate) granted_privileges.add(PrivilegeEnum.View)
elif (privilege == PrivilegeEnum.Administer): granted_privileges.add(PrivilegeEnum.Manage) granted_privileges.add(PrivilegeEnum.Operate) granted_privileges.add(PrivilegeEnum.ProxyView) granted_privileges.add(PrivilegeEnum.View)
def get_granted_privileges(acl, subject_desc, endpoint_id, cluster_id) -> set[Privilege]:
# Granted privileges set is initially empty granted_privileges = set()
# PASE commissioning channel implicitly grants administer privilege to commissioner if subject_desc.AuthMode == AuthModeEnum.PASE and
subject_desc.IsCommissioneeDuringCommissioning: add_granted_privilege(granted_privileges, PrivilegeEnum.Administer)
for acl_entry in acl:
# End checking if highest privilege is granted
if PrivilegeEnum.Administer in granted_privileges: break
# Fabric index must match, there are no valid entries with FabricIndex == 0
# other than the implicit PASE entry, which we will not see explicitly in the # access control list
if acl_entry.FabricIndex == 0: continue
if acl_entry.FabricIndex != subject_desc.FabricIndex: continue
# Auth mode must match
if acl_entry.AuthMode != subject_desc.AuthMode: continue
# Subject must match, or be "wildcard" if is_empty(acl_entry.Subjects):
# Precondition: only CASE and Group auth can have empty subjects
assert(acl_entry.AuthMode in [AuthModeEnum.CASE, AuthModeEnum.Group]) # Empty is wildcard, no match required
else:
# Non-empty requires a match matched_subject = False
for acl_subject in acl_entry.Subjects:
for isd_subject in subject_desc.Subjects:
if subject_matches(acl_subject, isd_subject): matched_subject = True
break
if matched_subject: break
if not matched_subject: continue
# Target must match, or be "wildcard" if is_empty(acl_entry.Targets):
# Empty is wildcard, no match required else:
# Non-empty requires a match matched_target = False
for target in acl_entry.Targets:
# Precondition: target cannot be empty
assert(target.Cluster != null or target.Endpoint != null or target.DeviceType
!= null)
# Precondition: target cannot specify both endpoint and device type assert(target.Endpoint == null or target.DeviceType == null)
# Cluster must match, or be wildcard
if target.Cluster != null and target.Cluster != cluster_id: continue
# Endpoint must match, or be wildcard
if target.Endpoint != null and target.Endpoint != endpoint_id: continue
# Endpoint may be specified indirectly via device type if target.DeviceType != null and not
endpoint_contains_device_type(endpoint_id, target.DeviceType): continue
matched_target = True break
if not matched_target: continue
# Extensions processing must not fail
if not extensions_are_valid(acl, acl_entry, subject_desc, endpoint_id, cluster_id): continue
# All checks have passed, add privilege to granted privilege set add_granted_privilege(granted_privileges, acl_entry.privilege)
# Should never grant Administer privilege to a Group. if subject_desc.AuthMode == AuthModeEnum.Group:
assert (PrivilegeEnum.Administer not in granted_privileges) return granted_privileges
The algorithm to derive the ISD from an incoming message takes as input:
The incoming message (message)
The Session ID of the incoming message (session_id)
A conceptual Sessions Metadata database (sessions_metadata)
DEFAULT_COMMISSIONING_PASSCODE = 0
enum AuthModeEnum {
None = 0, # conceptual "no auth" value PASE = 1,
CASE = 2,
Group = 3
}
struct SubjectDescriptor { bool IsCommissioning; AuthModeEnum AuthMode;
list<SubjectID> Subjects; # max 3 items FabricIndex FabricIndex;
}
The Group Key Management Cluster (group_key_management_cluster) The output of the algorithm is the SubjectDescriptor structure below:
The algorithm SHALL function as follows:
def get_isd_from_message(message) -> SubjectDescriptor: isd = {
IsCommissioning: False, AuthMode: AuthModeEnum.None, Subjects: [],
FabricIndex: 0
}
session_id = message.get_session_id()
if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.PASE: isd.AuthMode = AuthModeEnum.PASE
isd.IsCommissioning = True isd.Subjects.append(DEFAULT_COMMISSIONING_PASSCODE)
isd.FabricIndex = sessions_metadata.get_fabric_index(session_id) # may be zero else if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.CASE:
isd.AuthMode = AuthModeEnum.CASE isd.Subjects.append(sessions_metadata.get_src_node_id(session_id)) # CASE session may contain CATs which also serve as subjects
# Append all CATs if present (can be up to 3)
if sessions_metadata.has_src_case_authenticated_tags(session_id):
isd.Subjects.append(sessions_metadata.get_src_case_authenticated_tags(session_id)) isd.FabricIndex = sessions_metadata.get_fabric_index(session_id) assert(isd.FabricIndex != 0) # cannot be zero
else if sessions_metadata.get_auth_mode(session_id) == AuthModeEnum.Group: # Message is assumed to have been decrypted and matched properly prior to # this procedure occurring.
group_id = message.get_dst_group_id()
group_key_id = sessions_metadata.get_group_key_id(message)
# Group membership must be verified against Group Key Management Cluster
if group_key_management_cluster.group_key_map_has_mapping(group_id, group_key_id): isd.AuthMode = AuthModeEnum.Group
isd.Subjects.append(group_id)
isd.FabricIndex = sessions_metadata.get_fabric_index(message) assert(isd.FabricIndex != 0) # cannot be zero
else:
# Do nothing on error, ISD remains unchanged assert(isd.IsCommissioning == False) assert(isd.AuthMode == AuthModeEnum.None) assert(is_empty(isd.Subjects)) assert(isd.FabricIndex == 0)
return isd
The Data Model specifies which privilege is required for each data element, via its access qualities.
The Interaction Model specifies how each action is processed, for both its request and its response. This includes details on how the Interaction Model uses Access Control to determine whether to allow the request (i.e. continue processing), or to deny the request (and whether/how that is indicated in the response).
Determining whether to allow or deny an action for a request path entails:
Determining the required privilege for the action, given the request path and type of access requested;
Determining the set of granted privileges for the action, given the request path and requesting subject;
Checking whether the required privilege is present in the set of granted privileges:
If present, the action is allowed;
If not present, the action is denied.
Note that the Interaction Model may allow the action for some request paths while denying it for other request paths in the same action. Also, note that Access Control is merely one of the checks used by the Interaction Model, and an action that is allowed by Access Control may fail for other reasons.